Install and sign in for the first time

Start by installing dtxWiki on your computer or having an administrator prepare a team server. Once the server is ready, everyone can read and edit its workspaces through a browser without writing code or installing Python on each person's computer.

These instructions cover installation and first sign-in for dtxWiki v0.2.1. See the v0.2.1 release notes for features and upgrade requirements. A local Python or npm launch manages its worker; systemd and Docker retain their separate worker service. Before starting an existing database, follow the update procedure.

Choose your route

Your situation	What to do	Who handles installation?
Your administrator has prepared a team server	Ask for its web address and your account, then sign in	Your server administrator
You want to try it on your own computer	Use the local setup below	You or a technical helper
Several people need the same workspace	Follow Set up a shared server	Someone who manages the server

A workspace is a collection of knowledge with its own members and settings. An account is your sign-in identity. Joining an organization’s server does not automatically make you a member of every workspace.

Join a team server

1. Get the exact web address from the administrator, for example https://wiki.example.com.
2. Open it in your browser and use the available email/password or configured external sign-in method. The Account page shows an Automatic username, but that identifier is not used to sign in. To replace a temporary password, open Account (the person icon in the top bar) and choose Update password; a new password needs 8–128 characters.
3. Select the intended workspace in the workspace switcher. Your Personal Workspace is separate from a shared workspace.
4. If the shared workspace is missing, open Account → User ID → Copy user ID and ask its Owner to add that UUID, or use your registered account email. An SSO profile email is not necessarily an account email. See Accounts and workspace access.

If Sign up is unavailable, that is normal for a shared server: password signup is closed by default. Use the configured external sign-in or ask the server administrator how accounts are created. An external provider may also disallow new accounts. You can use Library, Context, and Search before connecting an AI app.

You are ready when: the Dashboard opens and the workspace name matches the one you intend to use.

Try dtxWiki on your own computer

1. Prepare the installation tool

Open PowerShell on Windows or Terminal on macOS/Linux. Installation needs internet access to download the app and dependencies. Everyday work happens in the browser.

The app uses Python 3.12 or later. Use uv if you have neither installation tool yet: follow its official installation instructions for your operating system. uv can obtain Python 3.12, so this route does not require a separate Python installation. After installing uv, close and reopen the terminal, then check:

uv --version

Expected result: a uv version appears. If the command is unknown, finish the tool's PATH setup and open a new terminal. Node.js is not required for Python-package installation. Ask a technical helper if preparing these tools is unfamiliar.

2. Install the package

Upgrading from v0.1.2? Stop v0.1.2, including a worker you started separately, and back up its data before you install and start v0.2.1. The first start of v0.2.1 upgrades the database, and v0.1.2 cannot open it afterward. Follow the upgrade steps in Backups and maintenance, including dtxwiki inputs audit before that first start. A new installation does not need them.

Install dtxwiki==0.2.1 from PyPI. These uv commands work in PowerShell and in macOS/Linux terminals:

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

Expected result: installation completes and the version command prints dtxwiki 0.2.1. If uv reports that its tool directory is missing from PATH, run uv tool update-shell, close and reopen the terminal, then try the version command again. See uv's tool guide.

Already use pipx? Install with pipx instead

Choose one installation method to avoid conflicting commands. pipx needs an installed Python 3.12+ interpreter; see the official pipx repository for installation and PATH setup.

Linux/macOS with the python3.12 command available:

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

Windows PowerShell with Python 3.12 and the py launcher installed:

py -3.12 --version
pipx install --python (py -3.12 -c "import sys; print(sys.executable)") "dtxwiki==0.2.1"
dtxwiki --version

The PowerShell expression supplies the actual Python 3.12 executable path. If either prerequisite is unknown, complete its installation or use uv above. If pipx reports a missing application directory on PATH, run pipx ensurepath and reopen the terminal.

The Python package includes the web interface. This installation route does not require Node.js.

3. Start the app and open the browser

dtxwiki

The app prepares its local database, starts its background processing, and then starts the web server. Once the server accepts connections, it tries to open http://127.0.0.1:21080/. If the browser does not open, enter that address yourself. Leave the terminal running; it is now the server and will not return to the prompt until stopped. To start without opening a browser, use dtxwiki serve --no-open; this still runs in the foreground with its background processing.

If dtxWiki cannot start, it prints an error and returns to the prompt. A last line such as dtxWiki init could not start; see the preceding error means that the cause is printed just above it. See Troubleshooting.

Expected result: the sign-in screen opens. There is no default account or password. Starting the app does not create your account or grant anyone server administration.

4. Create your account

1. Choose Sign up on the sign-in screen.
2. Enter your email and a password of 8–128 characters; spaces count as part of the password. Optionally enter a Display name of up to 32 characters. If you leave it empty, dtxWiki uses the part of your email before @, or User when that part cannot be used. Email is the login ID; the display name is how you appear in the app. Input over these limits is rejected, not shortened.
3. Keep Keep me signed in on this browser enabled only on a browser you intend to keep signed in.
4. Choose Sign up and wait for the Dashboard.

Expected result: you are signed in and own a private Personal Workspace. SMTP is optional: you can sign up and use the wiki without mail-based verification. Add email delivery later when you need verification, email recovery or supported email notifications.

5. Grant server administration

This step is for the person operating the local installation. Workspace ownership alone does not allow server settings management.

Administration commands need the app stopped. In the terminal running dtxWiki, press Ctrl+C and wait for the prompt to return. Then run these commands in the same terminal, replacing you@example.com with your registered email:

dtxwiki admin grant --email you@example.com
dtxwiki admin list

Start the app again:

dtxwiki

Expected result: the grant prints granted server-admin to you@example.com and your email appears in the list. Refresh your browser to access Settings → Deployment. Server-admin manages system settings; content access still follows workspace membership.

If you run dtxwiki admin while the app is still running, it stops with a long error ending in stop dtxWiki (server and worker) first: … and grants nothing. Stop the app with Ctrl+C, then run the command again.

Running the commands in the same terminal keeps the same OS user and DTXWIKI_* settings. In a new terminal, apply customized settings again; creating an arbitrary .env file alone does not configure local commands. If the command says no user exists, verify the exact email and the selected data/database path. The account must already exist. Do not create a new empty installation as a workaround.

The systemd production installer automatically creates and grants its initial administrator. Docker setup creates the account and grants administration explicitly. Team members do not need server-admin for ordinary wiki use.

6. Data location and background processing

The default database is inside the OS user's .dtxwiki/data/dtxwiki.sqlite: ~/.dtxwiki on Linux/macOS, or $env:USERPROFILE\.dtxwiki in Windows PowerShell. Keep the whole directory, including files, the local session secret and the OAuth signing key (oauth-jwt.pem). Local means this computer: 127.0.0.1 on a colleague's laptop points to their laptop, not yours.

The same dtxwiki terminal also runs background jobs such as Library extraction and previews, queued account email, and cleanup of unused attachments. You do not need a second terminal or a separate worker command. Background processing uses the app's own settings, including DTXWIKI_* variables set in that terminal. Processed jobs and errors appear in the same terminal; idle waiting is not logged. systemd and Docker deployments run their worker as a separate service.

Run only one dtxWiki for the same data. A second dtxwiki, or a worker started separately, is refused; starting the app while another process still uses the data shows dtxWiki is already running or storage is still active; stop the existing processes first. If you used v0.1.2 with dtxwiki-worker run in a second terminal, stop that worker before starting v0.2.1; it is no longer needed. Do not delete the .lock files in the data directory.

If the background worker itself stops, dtxWiki stops too and prints dtxWiki background worker stopped unexpectedly (exit code N); dtxWiki has stopped. Read the error above that line, fix the cause, and start dtxwiki again. A failed import does not stop the app; it only marks that Library item as failed.

Expected result: one terminal keeps the app reachable and processes background jobs without startup errors. Continue with Your first workspace and try a small Library import.

Stop and return later

Press Ctrl+C once in the terminal running dtxWiki. The app and its background processing stop together; this can take a few seconds while a request or job finishes. Data remains stored. Run dtxwiki again to resume and sign in with the same account; there is no need to register again. Stop dtxWiki before backups or maintenance, and arrange backups before storing important work. A different OS user or DTXWIKI_DATA_DIR selects different data.

For LAN access, background operation or automatic startup, follow Access and background operation.

See Troubleshooting if the browser cannot connect.

Optional: run with npm

If you already use Node.js, you can run the npm launcher instead. It requires Node.js 22 or later and uv or pipx. With pipx, Python 3.12 or later must already be installed; uv can download Python 3.12 when needed.

npx @dtxsuite/dtxwiki@0.2.1

The npm package launches the matching PyPI dtxwiki==0.2.1; it is not a separate application. Its first run downloads the Python application and dependencies. It uses the same local web address, default ~/.dtxwiki data directory and background processing described above: keep the command running, and press Ctrl+C once to stop everything together.

Install Node.js from its official download page if needed and confirm node --version reports 22 or later. Accept npm's download prompt when shown. Follow the same signup steps. To grant administration, stop the app with Ctrl+C, run these commands in the same terminal, then start npx @dtxsuite/dtxwiki@0.2.1 again:

npx @dtxsuite/dtxwiki@0.2.1 admin grant --email you@example.com
npx @dtxsuite/dtxwiki@0.2.1 admin list

Refresh your browser once the app is running again. These commands work in PowerShell and macOS/Linux terminals.

To keep the launcher command on your PATH, you can instead use npm install --global @dtxsuite/dtxwiki@0.2.1, then start it with dtxwiki and run the commands above as dtxwiki admin …. Choose one installation method rather than installing both the Python package and global npm launcher under the same command name.

Optional: build from the v0.2.1 source

Use the v0.2.1 release tag in a clean checkout on Linux or WSL2 with Bash, Git, GNU Make, Node.js 22.18.x, npm, Python 3.12, and pipx. Use a new directory so the installation does not alter an existing checkout:

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
make build-wheel
pipx install --python python3.12 dist/dtxwiki-0.2.1-py3-none-any.whl
dtxwiki

make build-wheel includes the web interface in the package. Building only the Python package with a generic build command can leave it out.

Share it with a team

Use the shared-server setup for remote access. It provides HTTPS, persistent storage, and a background worker. Binding the local trial to 0.0.0.0 does not provide those protections.

Local and production installations use different default data locations. Existing local accounts and files are not transferred automatically when you set up a shared server.

v0.2.1 does not include a desktop installer or a published container image. Docker users build the image from the v0.2.1 release tag.

AI integration and SMTP are optional. Start with ordinary browser use, then follow Connect an AI app if you want an AI assistant to consult the knowledge you have stored.

Use an external sign-in

A shared server can offer configured external providers. Accounts may have no email or local password; creating an account does not grant team membership. If an account already exists, sign in to it first and link the provider. See login methods and SSO operation.

---

Implementation evidence: app launch, background processing, signup and password rules, admin commands, refusal while running, data paths, npm launcher, worker.