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.

This 0.1-series manual currently uses the released v0.1.2 package in its installation examples. Keep the app and its background worker on that same version.

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 sign in with your email and password. There is no separate username. Replace a temporary password using Account → Password.
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, ask its owner to add your exact login email. See Accounts and workspace access.

If Sign up is unavailable, that is normal for a shared server: public account creation is closed by default. Ask the server administrator for an account. 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

The matching package is available on PyPI. These uv commands work in PowerShell and in macOS/Linux terminals:

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

Expected result: installation completes and the version command prints dtxwiki 0.1.2. 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.1.2"
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.1.2"
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 published 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 the application, and 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.

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, an optional Display name, and a password of at least eight characters. Email is the login ID; the display name is how you appear in the app.
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.

Keep the app running and open a second terminal with the same OS user and DTXWIKI_* environment settings. Replace you@example.com with your registered email:

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

Expected result: the grant succeeds 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 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. Start the worker

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 and the local session secret. Local means this computer: 127.0.0.1 on a colleague's laptop points to their laptop, not yours.

After granting administration, run this in the second terminal for Library source extraction and other background jobs:

dtxwiki-worker run

The worker keeps polling until stopped; idle operation is normal. The app does not start it automatically. App and worker must use the same version, OS user, data directory and database. New terminals do not copy environment variables set in the first terminal: apply customized settings again. Creating an arbitrary .env file alone does not configure local commands. Without the worker, imports can remain queued. systemd and Docker deployments start a worker automatically.

Expected result: the app stays reachable and the worker keeps running without startup errors. Continue with Your first workspace and try a small Library import.

Stop and return later

Press Ctrl+C in each terminal to stop the app and worker. Data remains stored. Run the same two commands to resume and sign in with the same account; there is no need to register again. Stop both 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 published 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.1.2

The npm package launches the matching PyPI dtxwiki==0.1.2; it is not a separate application. Its first run downloads the Python application and dependencies. It uses the same local web address and default ~/.dtxwiki data directory described above.

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, then use the second terminal to grant administration:

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

Refresh your browser after the grant. The following worker commands work in PowerShell and macOS/Linux terminals:

For Library extraction and queued jobs, open a second terminal with the same data/database settings. Use the command for your Python runner:

# With uv
uvx --python 3.12 --from "dtxwiki==0.1.2" dtxwiki-worker run

# With pipx
pipx run --spec "dtxwiki==0.1.2" dtxwiki-worker run

Running npx does not install dtxwiki-worker on your PATH. Stop both terminals before backup or maintenance. To keep the launcher command on your PATH, you can instead use npm install --global @dtxsuite/dtxwiki@0.1.2, then start it with dtxwiki. Choose one installation method rather than installing both the Python package and global npm launcher under the same command name.

If you reuse an existing database, check its revision identifiers before maintenance. A new installation does not need that conversion.

Optional: build from the v0.1.2 source

This route is for people who want to build the program themselves. Use Linux or WSL2 with Bash, Git, GNU Make, Node.js 22.18 or later, 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.1.2
cd dtxWiki-0.1.2
git checkout --detach v0.1.2
make install PYTHON=python3.12
make build-wheel
pipx install --python python3.12 dist/dtxwiki-0.1.2-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.1.2 does not include a desktop installer or a published container image. Docker users build the image from the v0.1.2 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.

---

Implementation evidence: app launch, signup and password rules, admin commands, data paths, npm launcher, worker.