Backups, upgrades, and graph maintenance

This 0.2-series procedure upgrades an installation to dtxWiki v0.2.1. Identify your installation method and complete backup, audit and migration before starting the services. Use the same package or launcher version throughout installation, maintenance and startup.

Prepare an update

1. Record your installation method, running version, data directory, database URL, configuration and previous package or image. Use the same OS account and environment for maintenance.
2. Stop the web server and every worker. For a local managed installation, Ctrl+C stops both. For systemd, use sudo systemctl stop dtxwiki dtxwiki-worker; for Compose, use docker compose stop app worker in the existing infra/prod directory.
3. Back up the complete data directory and configuration. Preserve ownership, secret files, OAuth signing keys, Library originals, Context media, deployment environment and proxy configuration. Include Caddy's pki directory when using its internal CA.
4. Keep the backup outside the directory being changed. Restore a copy in an isolated environment before relying on it. SQLite WAL files are part of the database state: stop all writers before copying the complete data set, or use a supported database-consistent backup. Do not copy only a live .sqlite file.
5. Verify the published release and matching Python/npm versions. Install the selected version without starting it, then audit and prepare the actual database before reopening access.

For external databases, back up the control database and every configured workspace database with their native tools, alongside the files and configuration. A database dump alone does not contain uploaded originals or secret keys.

Audit and migrate

For an existing v0.1.3 or v0.1.4 installation, after backup and installation of v0.2.1, keep both services stopped and run with its actual configuration:

dtxwiki --version
dtxwiki db revision-inventory
dtxwiki inputs audit
dtxwiki bootstrap
dtxwiki reindex
dtxwiki graph reproject --all-workspaces
dtxwiki db revision-inventory

Run bootstrap only after the audit succeeds. An audit exit code of 0 means no findings, 1 means findings were reported, and 2 means the audit failed. Read blocking scalar findings, repair the exact UUID with users set-display-name, users set-email or inputs repair-metadata as appropriate, and audit again. Preserved historical findings are different from current upgrade blockers. Inspect each command's --help before repair.

The v0.2.1 migration head is 5b7e5c149279. It merges the document-reference revision c58f1d2e890a and the Chats lookup-index revision b1d98889a4ad; both parents follow the earlier graph/co-access work. The graph/Inbox merge 1d8f1c08ca36 is an intermediate revision, not the final head. This upgrade also includes the ordinary starter-workspace change, external identity, review decisions, retained deletion, Inbox and scoped link state. Compare the inventory's code head and database revision and require consistency=consistent.

Reference storage supports the editor's References panel, address-based citations and MCP cite registration. Publishing a source version combines its in-text and registered references and updates citation graph relationships, including supported Agent targets. The schema migration does not rewrite historical bodies or turn old unresolved citation keys into valid documents. Inspect Unresolved citation guidance, replace obsolete markers with a document selected from References, and publish the checked version when it is ready.

Downgrading past the document-reference schema drops the new reference data; recreating its tables does not recover those registrations. To return to older software, restore the matching pre-upgrade backup instead of assuming an in-place database downgrade is lossless.

Older v0.1.2 installations

Read the preserved v0.1 upgrade procedure for password limits, input repairs and managed-worker changes. v0.1.2 passwords over 128 characters require recovery; an ordinary password-change form cannot verify them. An older separate local worker must stop before managed mode starts. Complete those prerequisites and the current audit; do not skip the final 0.2 migration and graph preparation.

Databases from unsupported early previews need their documented export/fresh-install route. For recognized legacy revision names, inspect dtxwiki db rename-revisions before applying its conversion. Conversion changes revision identifiers after checking schema; it is not a database upgrade and does not replace bootstrap or a backup.

Convert existing revision identifiers

For recognized legacy revision names, install the selected package with server and worker stopped and preview dtxwiki db rename-revisions. Verify the matching schema and recoverable backup before dtxwiki db rename-revisions --apply in that same environment. Never force-stamp an unsupported or inconsistent database. A successful conversion still needs the audit, bootstrap and final inventory checks.

Choose your update method

These commands install v0.2.1. Complete common preparation first. With a direct Python installation, use its dtxwiki for the audit, bootstrap, reindex and graph commands above. With a launcher, use that same pinned launcher throughout.

Existing installation	Continue below
uv	uv tool
pipx	pipx
pip in a virtual environment	pip
npx	npx
Global npm launcher	global npm
systemd with a wheel	verified local wheel
Docker Compose	source rebuild

Local package

uv tool

uv tool install --force --python 3.12 "dtxwiki==0.2.1"
dtxwiki --version

pipx

pipx install --force --python python3.12 "dtxwiki==0.2.1"
dtxwiki --version

pip virtual environment

Activate the existing dedicated environment first:

python -m pip install --upgrade "dtxwiki==0.2.1"
dtxwiki --version

npx

Starting npx @dtxsuite/dtxwiki@latest can start the server immediately. Select and verify one version instead; keep it fixed for preparation and startup:

npx @dtxsuite/dtxwiki@0.2.1 --version
npx @dtxsuite/dtxwiki@0.2.1 inputs audit

After a successful audit and any repairs:

npx @dtxsuite/dtxwiki@0.2.1 bootstrap
npx @dtxsuite/dtxwiki@0.2.1 reindex
npx @dtxsuite/dtxwiki@0.2.1 graph reproject --all-workspaces
npx @dtxsuite/dtxwiki@0.2.1 db revision-inventory

Only after verification, start npx @dtxsuite/dtxwiki@0.2.1. Use the same prefix for repairs. The npm package launches the matching Python package; dtxwiki update does not update this launcher.

Global npm launcher

npm install --global @dtxsuite/dtxwiki@0.2.1
dtxwiki --version

Use its dtxwiki for the preparation commands before starting the app. Avoid installing competing commands under the same PATH name.

systemd: a verified local wheel

Preserve /var/lib/dtxwiki, /etc/dtxwiki, the previous wheel and service configuration. Use the published version's installer/wheel procedure in deployment, retaining the existing service user, data paths and env file. Perform the audit and migration through sudo dtxwiki …, which loads that environment. Set DTXWIKI_WORKER_MODE=external when the separate dtxwiki-worker service runs. Reindex and reproject with the same wrapper before starting both services. A source-built wheel must include the frontend, graph assets, workers and license notices.

Docker: rebuild from a pinned version

Keep the existing checkout location, Compose project name, .env and data volume. Back up with app and worker stopped. Select the verified release tag v0.2.1, then run docker compose build from infra/prod. This documentation assumes a local image build; no registry image is implied.

Use docker compose run --rm --no-deps app dtxwiki inputs audit for the preflight, and the same prefix for repairs. After it passes, run bootstrap, reindex, graph reprojection and revision inventory with that prefix. Then docker compose up -d starts the existing services. Retain external worker mode when Compose runs the separate worker. Do not replace an existing deployment with a new Compose project that accidentally selects an empty volume.

Graph maintenance

Reindex refreshes stored search/navigation summaries and live link projections. Graph reprojection explicitly reconciles existing authored relationships across live Context versions; it does not invent missing citations or reconstruct a complete historical log.

dtxwiki graph reproject --workspace YOUR_WORKSPACE_UUID_OR_SLUG
dtxwiki graph degree-report --workspace YOUR_WORKSPACE_UUID_OR_SLUG --json

Use either --workspace or --all-workspaces for reprojection. It reports each workspace and a summary, rolls back a failed workspace and continues with others; exit 1 means at least one failed. Inspect the failed targets before retrying. A degree report is an operator diagnostic sample, not a user's permission-filtered map or a factual-quality score. Follow the same database configuration and maintenance window as the upgrade.

Owners still need to enable the workspace map, and each user needs the Labs preference. Turning on a map is separate from repairing its data. See Knowledge Map.

Check the running version and background work

1. Start the server using the existing method and confirm sign-in, the intended workspace and representative published pages.
2. Check the installation's dtxwiki --version, then the actual server's /health/live. Both should report 0.2.1. If they differ, confirm which environment and process are running before reopening access.
3. Check /health/ready. Managed mode reports components.worker=ok; external mode reports n/a, so separately check the systemd/Compose worker service and a real queued import.
4. Verify Library originals/media, Search, a review/history comparison including reference changes, Inbox and any configured SSO. Confirm a saved reference and a published citation in a practice page, then reload MCP tool catalogs and generated schemas for contract revision 29.
5. Confirm Knowledge Map's two settings and a known published link. Partial history is expected where no historical observation exists.

Settings → Deployment can check the public package index and show installation-specific guidance. Its successful, fresh result describes a published version; a failed or stale lookup is not evidence that no update exists. This card does not perform the upgrade. Select the manual series for your target version and follow the installation-specific procedure above.

Practice restoration

Close access and stop both services. Preserve the failed upgraded state separately, restore the full pre-upgrade database/files/configuration, reinstall the matching previous software, then check permissions, health and worker state. Software rollback alone cannot reverse database migrations. Never open the new 0.2 database with old code as a substitute for restoring the backup.

For an update managed by the built-in updater, sudo dtxwiki rollback --list lists its managed backups; sudo dtxwiki rollback --to-backup /var/lib/dtxwiki/backups/EXACT_BACKUP_ID uses a chosen backup and the matching previous package. Keep that package available. Manually supplied wheels and Docker require their corresponding saved wheel/image/source and full backup restoration.

Periodic cleanup removes eligible completed scheduled checks older than seven days and expired retry receipts in bounded batches. Failed/manual jobs and content-processing history are retained. SQLite can reuse freed pages without shrinking the file. Reclaim space only during an offline, backed-up maintenance window with the SQLite VACUUM procedure in the operator runbook.

Sources: migration files, graph commands, update card, deployment and recovery.