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.
This manual's current installation example uses v0.1.2. Pin the installer, app package and worker to that same release. A production installation uses its own data location; it does not automatically move accounts and files from a personal local installation.
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 published package and installer
On a Linux/WSL2 preparation machine, use Git and Python 3.12 with pip to download the published PyPI wheel. 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.1.2 https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.1.2
cd dtxWiki-0.1.2
python3.12 -m pip download --no-deps --only-binary=:all: --dest wheelhouse "dtxwiki==0.1.2"
sha256sum wheelhouse/dtxwiki-0.1.2-py3-none-any.whl infra/prod/install.sh
scp wheelhouse/dtxwiki-0.1.2-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
Use Linux/WSL2, Python 3.12, Node.js 22.18+, npm, Git, and GNU Make in a clean checkout:
git clone https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.1.2
cd dtxWiki-0.1.2
git checkout --detach v0.1.2
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.1.2-py3-none-any.whl infra/prod/install.sh
scp dist/dtxwiki-0.1.2-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.1.2-py3-none-any.whl /tmp/install.sh
chmod 0644 /tmp/dtxwiki-0.1.2-py3-none-any.whl
sudo bash /tmp/install.sh \
--domain wiki.example.com \
--email admin@example.com \
--tls acme \
--wheel /tmp/dtxwiki-0.1.2-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. Change the password using Account → Password. If you missed it, 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. 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. Running the executable inside /opt/dtxwiki/.venv directly as root without that environment can address a different database.
Option B: Docker Compose
There is no published v0.1.2 container image. Compose builds the image from the checkout:
git clone https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.1.2
cd dtxWiki-0.1.2
git checkout --detach v0.1.2
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 for a password of at least eight characters twice with hidden input 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.
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, 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.
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.
Version evidence: deployment runbook, production Compose stack.