Set up a shared server
This page is for the person who operates the server. Team members need only its web address and an account. A server is a computer that stays running so everyone can reach the same knowledge.
Before you install
Official production deployment uses SQLite on one server, with one app process and one worker. The worker processes background jobs. No separate database server is needed. Do not put the database on NFS or add replicas of the app or worker. Workspaces have separate access controls within the same database; a physical database for each workspace is not provided.
Both layouts below run the worker as its own service. The systemd setup writes DTXWIKI_WORKER_MODE=external to /etc/dtxwiki/dtxwiki.env and runs the worker as dtxwiki-worker.service; the Docker image defaults to external and uses the Compose worker service. dtxWiki refuses a second worker for the same database. A local dtxwiki, by contrast, runs its worker itself.
The examples use the v0.2.1 installer and app package from the same release. The app and worker services both run the installed package. A production installation uses its own data location; it does not automatically move accounts and files from a personal local installation. To move an existing v0.1.2 server to v0.2.1, follow Upgrade from v0.1.2 instead of installing again. For other maintenance, choose your update method.
Prepare:
- An Ubuntu 22.04+ server with root access for systemd, or 64-bit Linux with Docker Engine, Compose v2, and Git for Docker.
- A domain such as
wiki.example.comwhose DNS records point to the server; inbound ports 80 and 443 for public HTTPS. - Outbound access needed to install dependencies and obtain certificates.
- A protected backup destination separate from the application checkout. See Backups and maintenance.
Replace example domains and email addresses below with yours. Use a fresh server or review existing services before running the installer: it creates service accounts, installs packages, and configures Caddy, the HTTPS reverse proxy.
Option A: systemd on Ubuntu
1. Prepare the package and installer
On a Linux/WSL2 preparation machine, use Git and Python 3.12 with pip to download the dtxwiki==0.2.1 wheel from PyPI. This route does not need Node.js or a frontend build. The installer and wheel must come from the same release tag.
python3.12 --version
git clone --branch v0.2.1 https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.2.1
cd dtxWiki-0.2.1
python3.12 -m pip download --no-deps --only-binary=:all: --dest wheelhouse "dtxwiki==0.2.1"
sha256sum wheelhouse/dtxwiki-0.2.1-py3-none-any.whl infra/prod/install.sh
scp wheelhouse/dtxwiki-0.2.1-py3-none-any.whl operator@wiki.example.com:/tmp/
scp infra/prod/install.sh operator@wiki.example.com:/tmp/install.sh
Use a new checkout directory. Replace the SSH account and server hostname with your own. Record the SHA-256 results and compare them on the server after transfer. The --no-deps download obtains the dtxWiki wheel; the installer obtains its Python dependencies later.
Optional: build a wheel yourself
Build from the published v0.2.1 tag in a clean checkout using Linux/WSL2, Python 3.12, Node.js 22.18.x, npm, Git, and GNU Make:
git clone https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.2.1
cd dtxWiki-0.2.1
git checkout --detach v0.2.1
make install PYTHON=python3.12
npm run playwright:install
make test-packaged
.venv/bin/python scripts/verify_wheel_artifact.py dist
sha256sum dist/dtxwiki-0.2.1-py3-none-any.whl infra/prod/install.sh
scp dist/dtxwiki-0.2.1-py3-none-any.whl operator@wiki.example.com:/tmp/
scp infra/prod/install.sh operator@wiki.example.com:/tmp/install.sh
make test-packaged builds the wheel and checks the installed web interface and API. Use a clean checkout so dist contains only this build. Record the SHA-256 results; compare them after transfer to confirm that both files arrived unchanged.
Do not install an unspecified "latest" package when you intend to run the documented example version.
2. Install on the server
ssh operator@wiki.example.com
sha256sum /tmp/dtxwiki-0.2.1-py3-none-any.whl /tmp/install.sh
chmod 0644 /tmp/dtxwiki-0.2.1-py3-none-any.whl
sudo bash /tmp/install.sh \
--domain wiki.example.com \
--email admin@example.com \
--tls acme \
--wheel /tmp/dtxwiki-0.2.1-py3-none-any.whl
The installer prepares Python, Caddy, the service account, configuration, database, services, and initial owner account. It grants that initial account server-admin automatically. The wheel fixes the dtxWiki version; its Python dependencies still come from the configured package index.
Copy the initial temporary password when it is shown: it appears once. On your computer, open https://wiki.example.com/ and sign in with the --email address and that password; no browser needs to run on the server. Then choose your own password in Account → Update password; a new password needs 8–128 characters. If you missed the temporary password, issue a one-time reset link from an interactive server terminal:
sudo dtxwiki users issue-password-reset admin@example.com --delivery link
Give that link to the intended account owner securely. The recipient chooses their own password; do not capture the link in shared logs.
3. Check that it works
sudo systemctl --no-pager --full status dtxwiki dtxwiki-worker caddy
curl -fsS https://wiki.example.com/health/live
curl -fsS https://wiki.example.com/health/ready
curl -i https://wiki.example.com/mcp
Both health requests should succeed. The unauthenticated /mcp request should return 401 with an authentication challenge; this means credentials are required. Both app and worker should be active. The readiness response lists "worker":"n/a" because the app does not check the separate worker service, so rely on the systemctl status output for dtxwiki-worker. Finally, sign in in a browser, confirm your Personal Workspace and Settings → Deployment, create a practice Context page, and confirm that it is still available after a service restart. Follow service operation for startup, logs and shutdown.
Use sudo dtxwiki ... for systemd administration. The installed wrapper reads /etc/dtxwiki/dtxwiki.env, so commands use the production database, and it runs data commands such as users, workspace, admin, bootstrap and inputs as the dtxwiki service account. Running the executable inside /opt/dtxwiki/.venv directly as root without that environment can address a different database.
Option B: Docker Compose
The inspected source uses a local Docker build; no registry image is assumed for v0.2.1. Compose builds the image from a checkout of the v0.2.1 release tag:
git clone https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.2.1
cd dtxWiki-0.2.1
git checkout --detach v0.2.1
cd infra/prod
cp .env.docker.example .env
Edit .env and set DTXWIKI_DOMAIN=wiki.example.com and DTXWIKI_ADMIN_EMAIL=admin@example.com. The email is for certificate notices; it does not create a dtxWiki account. Keep .env private, especially if you add mail credentials later.
docker compose up -d --build
docker compose ps
docker compose exec app dtxwiki users add admin@example.com
docker compose exec app dtxwiki admin grant --email admin@example.com
curl -fsS https://wiki.example.com/health/ready
users add asks twice, with hidden input, for a password of 8–128 characters and creates the account's Personal Workspace. admin grant gives this existing account server administration rights. Open the HTTPS server URL, sign in with that email/password, and check Settings → Deployment. The initial init service creates keys and prepares the database before the app and worker start. Persistent data, keys, and the session secret live in the data volume.
The image starts the app with DTXWIKI_WORKER_MODE=external, so the Compose worker service processes background jobs and /health/ready reports "worker":"n/a". Do not add DTXWIKI_WORKER_MODE to the Compose services: a v0.1.2 image rejects that setting, which would break a return to v0.1.2. Only a single container that runs without the worker service needs DTXWIKI_WORKER_MODE=managed.
Keep the same checkout location and Compose project name for later updates. Removing volumes or creating a different project can leave you with an empty database. Never use docker compose down -v as an update procedure.
Internal networks and existing proxies
| Network | systemd installer TLS mode | What else is needed? |
|---|---|---|
| Public domain | --tls acme | Correct DNS and reachable 80/443 |
| Internal hostname or IP | --tls internal | Distribute and trust Caddy’s root CA on each browser and MCP client |
| Certificate you already own | --tls custom | Supply --tls-cert and --tls-key |
| Existing HTTPS proxy | --tls external | Set --forwarded-ip to the trusted proxy IP; for a proxy on another machine, set --bind-host and restrict the app port to that proxy |
Plain HTTP (--tls none --insecure-eval) is for evaluation and does not support standards-compliant OAuth onboarding. Follow the deployment runbook for certificate trust and Docker internal-CA configuration.
Add people and maintain the server
Public sign-up is closed by default for team and remote modes. Create accounts with sudo dtxwiki users add person@example.com, which asks twice for a password of 8–128 characters, then let workspace owners grant membership. See Accounts and access.
Settings → Deployment displays server status for server administrators. Change server configuration with the CLI; the web app does not write system configuration files. Keep data, keys, and configuration together in backups, and follow Backups and maintenance before changing versions.
Unused attachments. DTXWIKI_CONTEXT_MEDIA_ORPHAN_RETENTION_HOURS sets the server default for uploads that no page uses: periodic cleanup reclaims them once they are older than this many hours since upload. The default is 168 hours (7 days), and 0 turns automatic cleanup off by default. Workspace owners can choose their own period, or switch cleanup off, in Settings → Attachments; a value they save is stored in the database and takes precedence over the server default, even when that default is 0. Set the default for both services on systemd:
sudo dtxwiki config set DTXWIKI_CONTEXT_MEDIA_ORPHAN_RETENTION_HOURS=72
sudo systemctl restart dtxwiki dtxwiki-worker
The bundled Docker Compose file does not pass this variable, so Docker installations use the 168-hour default; workspace owners can still set their own period.
Optional email delivery
SMTP is not required for account creation, login or ordinary wiki use. Add it when you need email verification, email recovery or supported notifications. Follow Email and SMTP, including the Gmail example, and apply the same mail environment to the app and worker. HTTPS and a verified account email are prerequisites for self-service email recovery.
v0.2.1 deployment checks
Use the matching v0.2.1 installer, wheel and source tag. Existing installations must complete backup, migration and reprojection first. External sign-in needs a separately configured plugin. DTXWIKI_GRAPH_SERVICE_AVAILABLE=false disables workspace maps server-wide; local Context graphs are independent.
Version evidence: deployment runbook, production Compose stack, installer and sudo dtxwiki wrapper, systemd worker mode, container worker mode, readiness check, password and account limits, attachment retention.