Operator documentation and docs site

agent-pi commented

2026-10-16 20:05:23 +00:00

Collaborator

Xique can be run as a container deployment (phase 1e), but nothing tells an operator how. There is no deployment walkthrough, no upgrade procedure, and no backup/restore guidance — including how the worker's WAL checkpointing behaviour affects backups and what a safe copy looks like.

The repository also has no documentation site: the deploy-docs CI job is written but disabled until docs exist, and there is no mkdocs configuration, nav, or pages branch.

This issue covers the operator-facing documentation and the site that serves it, as a follow-up to the container-only phase 1e (#6).

Xique can be run as a container deployment (phase 1e), but nothing tells an operator how. There is no deployment walkthrough, no upgrade procedure, and no backup/restore guidance — including how the worker's WAL checkpointing behaviour affects backups and what a safe copy looks like. The repository also has no documentation site: the `deploy-docs` CI job is written but disabled until docs exist, and there is no mkdocs configuration, nav, or `pages` branch. This issue covers the operator-facing documentation and the site that serves it, as a follow-up to the container-only phase 1e (#6).

agent-pi referenced this issue

2026-10-16 20:05:42 +00:00

Phase 1e — Ops & Containers #6

agent-pi referenced this issue

2026-10-16 21:16:49 +00:00

Phase 1e — container image, entrypoint, and podman quadlets #17

forgejo-actions referenced this issue

2026-10-16 22:11:56 +00:00

Phase 1e — container image, entrypoint, and podman quadlets #17

agent-pi referenced this issue

2026-10-16 22:22:55 +00:00

Phase 1e — container image, entrypoint, and podman quadlets #17

agent-pi added the

Kind/Documentation

Priority

Medium

labels

2026-10-17 00:19:06 +00:00

agent-pi commented

2026-10-17 02:37:00 +00:00

Author

Collaborator

Plan of attack (mkdocs + Material, yunjin's stack):

Site scaffold — mkdocs.yml (Material with dark/light toggle, site_url: https://xique.marvin8.zone, mike versioned-docs plugin, revision-date plugin) and a docs/ tree:
- index.md — what xique is, the web/worker/sqlite shape, where to go next
- install.md — container bring-up from deploy/: prerequisites, the five quadlets, env file, first-boot ordering (web refuses an unmigrated DB until the worker migrates), Tailscale node approval, /setup
- upgrade.md — pull/restart, the worker owns migrations (web refuses a behind-schema DB), rollback via release tags
- backup.md — what WAL mode means for backups, the worker's per-cycle wal_checkpoint(TRUNCATE), safe copy procedures (stopped-pod copy and online .backup), restore, what not to back up
- config.md — the full XIQUE_* reference
- cli.md — xique import-trakt, including the container-exec form
  Content builds on (not contradicts) the README's Running it section, which keeps its quick-start role.
Docs deps — mike~=2.2.0, mkdocs~=1.6.1, mkdocs-material~=9.7.7, mkdocs-git-revision-date-localized-plugin~=1.6.0 in the dev group; uv.lock/pylock.toml regenerated in the same commit.
Enable deploy-docs — replace if: ${{ false }} with yunjin's gate github.event_name == 'release' && !github.event.release.prerelease (the job's version-tag guard and mike flow already assume release refs). The first publish run is expected to fail pending the operator's one-time manual step; subsequent runs proceed.

Branch: feat/issue-16-operator-docs

Commits:

:memo: docs: add the operator documentation site
:construction_worker: ci: deploy docs on release

PR: POST /repos/marvin8/xique/pulls (head feat/issue-16-operator-docs, base main, Closes #16).

Plan of attack (mkdocs + Material, yunjin's stack): 1. **Site scaffold** — `mkdocs.yml` (Material with dark/light toggle, `site_url: https://xique.marvin8.zone`, mike versioned-docs plugin, revision-date plugin) and a `docs/` tree: - `index.md` — what xique is, the web/worker/sqlite shape, where to go next - `install.md` — container bring-up from `deploy/`: prerequisites, the five quadlets, env file, first-boot ordering (web refuses an unmigrated DB until the worker migrates), Tailscale node approval, `/setup` - `upgrade.md` — pull/restart, the worker owns migrations (web refuses a behind-schema DB), rollback via release tags - `backup.md` — what WAL mode means for backups, the worker's per-cycle `wal_checkpoint(TRUNCATE)`, safe copy procedures (stopped-pod copy and online `.backup`), restore, what not to back up - `config.md` — the full `XIQUE_*` reference - `cli.md` — `xique import-trakt`, including the container-exec form Content builds on (not contradicts) the README's Running it section, which keeps its quick-start role. 2. **Docs deps** — `mike~=2.2.0`, `mkdocs~=1.6.1`, `mkdocs-material~=9.7.7`, `mkdocs-git-revision-date-localized-plugin~=1.6.0` in the dev group; `uv.lock`/`pylock.toml` regenerated in the same commit. 3. **Enable `deploy-docs`** — replace `if: ${{ false }}` with yunjin's gate `github.event_name == 'release' && !github.event.release.prerelease` (the job's version-tag guard and mike flow already assume release refs). The first publish run is expected to fail pending the operator's one-time manual step; subsequent runs proceed. Branch: `feat/issue-16-operator-docs` Commits: - `:memo: docs: add the operator documentation site` - `:construction_worker: ci: deploy docs on release` PR: `POST /repos/marvin8/xique/pulls` (head `feat/issue-16-operator-docs`, base `main`, `Closes #16`).

agent-pi referenced this issue from a pull request that will close it,

2026-10-17 02:42:14 +00:00

Add the operator documentation site and enable docs deployment #36

agent-pi closed this issue

2026-10-17 04:45:26 +00:00

Rows
Columns

Operator documentation and docs site #16