Files
pages/README.md
T
Anya Tokugawa b312a50d37
Build and publish container images / images (push) Successful in 10m38s
Release container images / release (push) Successful in 24s
Adopt SemVer 2.0.0 and promote release images by digest
2026-09-27 19:52:58 +09:00

89 lines
3.3 KiB
Markdown

# pageswiki
Simplest and powerful wiki architecture for personal
## Container CI
Gitea Actions tests and builds the application, adaptor gateway, and Excalidraw
viewer, then publishes them to the Gitea container registry with commit-SHA tags.
See [Gitea image builds and registry setup](docs/operations/gitea-images.md) for
runner requirements, registry secrets, and the optional registry Compose overlay.
The workflow does not deploy to production.
PagesWiki follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
Release tags (starting with `v0.1.0`) promote existing tested images without
rebuilding. See the [versioning and release policy](docs/operations/versioning.md).
## Knowledge City Model
Pages Wiki uses urban language for its content hierarchy:
```text
Campus → Domain → Zone (Quartier / Street) → Spot → Page
```
- **Campus** manages a group of Domains.
- **Domain** is a site space selected by a host or subdomain.
- **Zone** is the managed tree containing Quartiers and Streets.
- **Quartier** is a planned aggregation of Streets.
- **Street** groups Spots as the smallest city block.
- **Spot** is the smallest knowledge group.
- **Page** is the smallest knowledge unit and is identified by UUID, not path.
A Page may be linked from multiple Spots. Semantic paths are projections and
must not be treated as Page identity.
## Data CLI
The CLI in `data/pageswiki-cli` provides rsync-like transfers and an
interactive Semantic Path shell over SQLite and `data/documents/`:
```bash
data/pageswiki-cli put article.html path:/quartier/street/spot/page
data/pageswiki-cli get path:/quartier/street/spot/page article.html
data/pageswiki-cli shell
PAGESWIKI_DOMAIN=engineering data/pageswiki-cli ls /
```
The shell supports `ls`, `cd`, `cat`, `view`, `edit`, transfer, Revision,
diff/restore, and link commands, with tab completion and persistent history.
`view` uses `PAGER`; `edit` uses `EDITOR`.
Set `PAGESWIKI_DATA_DIR` when inspecting a different data directory.
`PAGESWIKI_DOMAIN` selects the active Domain by name, UUID, or host. In the
interactive shell, `domain [NAME|UUID|HOST]` displays or changes it.
An instance can enroll into a Controller Campus during container startup:
The included Docker Compose configuration enrolls `app2` into a Controller
Campus. Copy `.env.example` to `.env` and set
`PAGESWIKI_EXTERNAL_CAMPUS_TOKEN` to the controller-issued enrollment token
before running Compose. The token is intentionally not committed; `.env` is
excluded from Git and Docker build contexts. Keep it private (for example,
`chmod 600 .env`).
```bash
PAGESWIKI_INSTANCE_FQDN=node.example.test \
pageswiki --add-external-campus campus.example.test "$CAMPUS_TOKEN"
```
For an explicitly trusted development network without TLS:
```bash
PAGESWIKI_INSTANCE_FQDN=node.internal.test \
pageswiki --add-external-campus-http campus.internal.test "$CAMPUS_TOKEN"
```
For a node dedicated to externally managed Domains, add
`--no-default-campus`. Its bootstrap Campus and Domain remain while approval
is pending, then are removed after the first assigned Domain is pulled:
```bash
PAGESWIKI_INSTANCE_FQDN=node.internal.test \
pageswiki --no-default-campus \
--add-external-campus-http campus.internal.test "$CAMPUS_TOKEN"
```
The controller records the instance public-key fingerprint. Domain placement
only offers instances whose fingerprint has been approved.