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 and opens a browser	Start it again yourself
dtxwiki serve --no-open	Runs the app without opening a browser	Start it again yourself; this is still a foreground process
nohup or a separate Windows console	Lets the app continue independently of the original terminal	No automatic start at boot or restart after failure
Installed systemd or Docker services	Manages a persistent app and worker	Uses the configured service restart behavior

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 and worker with Ctrl+C; avoid starting a second server on the same 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.1.2. The URL above automatically allows its IP; there is no need to duplicate it in DTXWIKI_ALLOWED_HOSTS.

5. In a second terminal, apply the same customized environment and start the same-version worker using the command from installation.
6. 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.

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

To return to default local use, stop both processes and remove the example URL from each 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 both existing processes. 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.1.2 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.

Read the app log with tail -f dtxwiki.log. 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.

The app still needs a worker. You can keep it in its second terminal, or for an installed uv/pipx package run:

nohup dtxwiki-worker run > dtxwiki-worker.log 2>&1 < /dev/null &

For an npm/uv runner, use nohup uvx --python 3.12 --from 'dtxwiki==0.1.2' dtxwiki-worker run > dtxwiki-worker.log 2>&1 < /dev/null &. A pipx runner uses pipx run --spec 'dtxwiki==0.1.2' dtxwiki-worker run after nohup, with the same log redirection.

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. The npm wrapper PID alone can leave its Python child running. For the worker, inspect ps -ax -o pid,command and identify your actual dtxwiki-worker run process by its command and installation path, then send it kill -TERM WORKER_PID. Identify each process before stopping it; stop both before maintenance.

Confirm the server no longer listens and the worker has exited. nohup does not configure startup at boot or automatically restart crashed processes.

Windows: keep separate app and worker windows

After a successful foreground launch, stop the existing processes. 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.1.2 serve --no-open"

The new process inherits this PowerShell's environment. 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.

Start a worker in a second console:

# uv/pipx installation
Start-Process dtxwiki-worker -ArgumentList "run"

For npm with uv, use Start-Process uvx -ArgumentList "--python 3.12 --from dtxwiki==0.1.2 dtxwiki-worker run". With pipx, use Start-Process pipx -ArgumentList "run --spec dtxwiki==0.1.2 dtxwiki-worker run".

Closing the original PowerShell does not close these separate processes. Stop each with Ctrl+C in its own console. These windows do not provide restart after failure or boot-time startup. Windows local use is distinct from the Linux production hosting workflow.

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. 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

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. An app health check alone does not prove the worker has processed a job. Follow Troubleshooting if either process fails, and optional SMTP setup for mail delivery.

---

Implementation evidence: serve options and browser URL, host policy, environment settings, worker, production setup, Compose stack.