Access and background operation

Use this page after installation and first login work. It is for the person running the app. Other users need the server's address and their account, not these commands.

Choose how to keep it running

Method	What it does	After reboot or failure
dtxwiki in a terminal	Runs the local app with its background worker and opens a browser	Start it again yourself
dtxwiki serve --no-open	Runs the app with its background worker, without opening a browser	Start it again yourself; this is still a foreground process
nohup or a separate Windows console	Keeps the app, with its background worker, running independently of the original terminal	No automatic start at boot or restart after failure
Installed systemd or Docker services	Runs a persistent app and a separate worker service	Uses the configured service restart behavior

A local dtxWiki starts its background worker itself and stops it when the app stops. The worker handles jobs such as Library extraction, queued account email and attachment cleanup. Every local method above therefore needs one command and one stop action; no separate worker command is needed. If a script or shortcut from v0.1.2 also starts a worker, remove that part: a second worker for the same data is refused.

If you arrange automatic start yourself, for example with your operating system's startup tools or a process manager, have it run only dtxwiki serve --no-open with the same OS user and settings. A process manager that must start the worker as its own process needs external mode.

To check a running app, open http://127.0.0.1:21080/health/ready on the same computer. "status":"ready" with "worker":"ok" means that the app and its background worker are ready. A server administrator can also open Settings → Deployment: Health shows Ready, or Degraded with a list of components that includes Background processing.

A computer must stay on for other people to reach it. For regular shared use, follow Set up a shared server rather than relying on a personal terminal.

Understand the addresses

Setting or address	Meaning
http://127.0.0.1:21080/	The default local app on the computer opening this URL
serve --host 0.0.0.0	Listen on all IPv4 interfaces; 0.0.0.0 is a bind setting, not the URL to give people
DTXWIKI_PUBLIC_BASE_URL	The actual representative URL, used for server links and public metadata; its host is automatically allowed
DTXWIKI_ALLOWED_HOSTS	Additional allowed hostnames/IP addresses, separated by commas; example wiki.lan,192.168.1.20
HTTPS reverse proxy	Supplies HTTPS in a production deployment; setting a URL alone does not install a certificate

The app accepts loopback names (localhost, 127.0.0.1, ::1), the representative URL's host, and additional allowed hosts. IP access still needs an allowed IP. Keep the check enabled and name the intended hosts; DTXWIKI_ALLOWED_HOSTS=* disables it for every hostname and IP.

The bundled UI uses its own server's API, so access through that same address does not require a separate CORS configuration. A browser that displays a Host error has reached the app; first check the requested hostname/IP against these settings.

Try another device on a trusted LAN

This is an HTTP evaluation example. HTTP does not encrypt passwords or session cookies. For continuing team use, internet access or mail recovery, set up HTTPS deployment. An internal network can use the TLS options in that guide.

1. Confirm local login works first.
2. Stop the existing app with Ctrl+C; its background worker stops with it. A second dtxWiki for the same data is refused, even on another port.
3. Find the server computer's LAN IP. Replace 192.168.1.20 below with that IP.
4. Apply the URL and restart the app.

Linux/macOS:

export DTXWIKI_PUBLIC_BASE_URL=http://192.168.1.20:21080
dtxwiki serve --host 0.0.0.0 --port 21080 --no-open

Windows PowerShell:

$env:DTXWIKI_PUBLIC_BASE_URL = "http://192.168.1.20:21080"
dtxwiki serve --host 0.0.0.0 --port 21080 --no-open

For npm, replace dtxwiki with npx @dtxsuite/dtxwiki@0.2.1. The URL above automatically allows its IP; there is no need to duplicate it in DTXWIKI_ALLOWED_HOSTS. The background worker uses the same settings as the app, including this URL.

5. On the other device, open http://192.168.1.20:21080/ and sign in. Allow the server's TCP 21080 port through its firewall for intended LAN devices. Virtual machines and WSL may need additional network forwarding; consult Microsoft's WSL networking guide.

Expected result: both devices reach the same server and accounts. Shared workspace access still depends on membership; allowing a host does not grant content access. The default local mode also allows signup, so everyone who can reach it may create an account unless that setting is changed.

To connect an AI app over this LAN, use an access key. With the representative URL set to the server's private IP address, Access key setup in Settings → MCP access can show setup commands for http://192.168.1.20:21080/mcp. A hostname such as wiki.lan over plain HTTP is not accepted, and OAuth needs HTTPS. The key travels unencrypted, so use it only on a trusted network and revoke it when the evaluation ends. See Connect an AI app.

Environment variables set in a terminal apply to that process and its children, including the app's background worker. A new terminal does not inherit changes from the first terminal. Apply the same DTXWIKI_DATA_DIR, database and other settings to the app and to administration commands. An arbitrary .env file is not automatically loaded by local CLI commands.

To return to default local use, stop the app with Ctrl+C and remove the example URL from its terminal before restarting:

# Linux/macOS
unset DTXWIKI_PUBLIC_BASE_URL

# Windows PowerShell
Remove-Item Env:DTXWIKI_PUBLIC_BASE_URL -ErrorAction SilentlyContinue

Use the normal local command without --host 0.0.0.0. If you also added a firewall rule for evaluation, remove that rule when it is no longer needed.

Linux/macOS: run the local app in the background

First complete a foreground launch and stop the existing app. Keep the same OS user and environment; changing either can select different data.

For uv/pipx installations:

nohup dtxwiki serve --no-open > dtxwiki.log 2>&1 < /dev/null &

For npm:

nohup npx --yes @dtxsuite/dtxwiki@0.2.1 serve --no-open > dtxwiki.log 2>&1 < /dev/null &

Add --host 0.0.0.0 --port 21080 only when you intend the LAN access above and have applied its URL setting. --yes accepts npm's package-download prompt, so use it after you have confirmed the first interactive launch.

The background app starts its own worker. Read the log with tail -f dtxwiki.log; it also contains the worker's processed jobs and errors. Ctrl+C stops following the log; it does not stop the background app. Log files are created in the directory where you ran the command.

Stop the actual processes

Find the process listening on the app's port, using lsof if installed:

lsof -nP -iTCP:21080 -sTCP:LISTEN

Use kill -TERM SERVER_PID, replacing SERVER_PID with the listener's actual PID. dtxWiki stops its web server and then its background worker, which gets up to 10 seconds to finish its current step. With npm, use the listener's PID rather than the launcher's own PID. Identify the process before stopping it, and stop it before maintenance.

Confirm that nothing listens on the port any more and that no worker remains: in ps -ax -o pid,ppid,command, the worker is a child of the app whose command contains backend.worker.managed. If the app does not stop, kill -KILL SERVER_PID ends it; its worker then exits by itself within about 10 seconds, and starting dtxWiki before that is refused with dtxWiki is already running or storage is still active. nohup does not configure startup at boot or automatically restart crashed processes.

Windows: keep the app in its own window

After a successful foreground launch, stop the existing app. From PowerShell with the same environment, open an app console:

# uv/pipx installation
Start-Process dtxwiki -ArgumentList "serve --no-open"

Or for npm:

Start-Process npx.cmd -ArgumentList "--yes @dtxsuite/dtxwiki@0.2.1 serve --no-open"

The new process inherits this PowerShell's environment and starts its own background worker. If LAN access is needed, set its representative URL first and include the bind options in ArgumentList. Keep the new console visible so you can check startup errors.

Closing the original PowerShell does not close this separate console. Stop dtxWiki with Ctrl+C in its own console; its background worker stops too. The window does not provide restart after failure or boot-time startup. Windows local use is distinct from the Linux production hosting workflow.

Run administration commands

Local administration commands such as dtxwiki admin …, dtxwiki users … and dtxwiki bootstrap need the app stopped. While the app runs, they stop with an error that includes stop dtxWiki (server and worker) first and change nothing.

1. Stop the app with Ctrl+C in its terminal, or stop a background app as shown above.
2. Run the command with the same OS user and settings. npm users run it as npx @dtxsuite/dtxwiki@0.2.1 ….
3. Start the app again.

dtxwiki inputs audit only reads the database, so it also works while the app runs.

Administrators can run administration and account commands beside a running app after that app has prepared the database. Set DTXWIKI_AUTO_BOOTSTRAP=false for that command only; the command then checks the database instead of preparing it:

DTXWIKI_AUTO_BOOTSTRAP=false dtxwiki admin list

$env:DTXWIKI_AUTO_BOOTSTRAP = "false"
dtxwiki admin list
Remove-Item Env:DTXWIKI_AUTO_BOOTSTRAP

Do not keep this setting for starting dtxwiki: after an upgrade, the app would refuse to start instead of upgrading its database. dtxwiki bootstrap and the input repairs (dtxwiki users set-display-name, dtxwiki users set-email and dtxwiki inputs repair-metadata) always need dtxWiki stopped.

Installed services already work this way: sudo dtxwiki users … and docker compose exec app dtxwiki … run beside the services, while sudo dtxwiki bootstrap and the input repairs need the services stopped.

Run the worker yourself (external mode)

This advanced mode is for operators whose own process manager starts the background worker as a separate process. dtxWiki also requires it when the configured database is not a regular local SQLite file. Ordinary local use and the installed systemd and Docker services do not need this section. It uses the dtxwiki-worker command from the Python package.

1. Stop every dtxWiki process that uses these data.
2. Give every command below the same settings: DTXWIKI_DATA_DIR, the database, secrets and mail settings, plus DTXWIKI_WORKER_MODE=external and DTXWIKI_AUTO_BOOTSTRAP=false. Instead of the environment variable, the app also accepts --worker-mode external.
3. Prepare the database once:

export DTXWIKI_WORKER_MODE=external
export DTXWIKI_AUTO_BOOTSTRAP=false
dtxwiki bootstrap

4. Let your process manager start the app with dtxwiki serve --no-open and exactly one worker with dtxwiki-worker run, in either order.

A second worker for the same database is refused. After installing a new version, stop both, run dtxwiki bootstrap again, then start both. In this mode /health/ready reports "worker":"n/a" because the app does not watch your worker; check that process yourself.

Manage an installed production service

Complete shared-server installation first. A pipx/uv installation alone does not create these services.

For installed Ubuntu systemd services:

sudo systemctl enable --now dtxwiki dtxwiki-worker
sudo systemctl --no-pager --full status dtxwiki dtxwiki-worker
sudo journalctl -u dtxwiki -u dtxwiki-worker -f

The first command enables startup at boot and starts both services. Check that both are active. Ctrl+C stops log viewing. To stop the services themselves:

sudo systemctl stop dtxwiki dtxwiki-worker

Both services read /etc/dtxwiki/dtxwiki.env. Setup and sudo dtxwiki update write DTXWIKI_WORKER_MODE=external into it, so the dtxwiki service does not start a second worker beside dtxwiki-worker. Keep that line while dtxwiki-worker.service is enabled. Use sudo dtxwiki ... for administration through the installed environment-loading wrapper. Production data defaults to /var/lib/dtxwiki; it is not automatically copied from a local user's .dtxwiki directory.

For an existing Docker installation, run from the same infra/prod directory and Compose project:

docker compose up -d
docker compose ps
docker compose logs --tail=50 app worker

The image runs the app without its own worker, and the Compose worker service processes the jobs. Do not add DTXWIKI_WORKER_MODE to the Compose configuration. Stop its writers with docker compose stop app worker. Keep the persisted volumes; removing them is not a shutdown or update procedure.

Expected result: app and worker are running, /health/ready succeeds at the actual HTTPS server URL, and a browser can sign in and read a saved page. For these services /health/ready reports "worker":"n/a" because it does not check the separate worker, so also confirm that dtxwiki-worker or the worker container is running. Follow Troubleshooting if either process fails, and optional SMTP setup for mail delivery.

---

Implementation evidence: serve options and browser URL, managed worker start and stop, storage guards, command refusal while running, readiness, host policy, environment settings, worker, production setup, Compose stack.