Optional email delivery (SMTP)

SMTP configuration is optional. You can sign up, sign in, write, organize, and search in a basic local installation without a mail server. The default is DTXWIKI_MAIL_PROVIDER=none. Local use at http://127.0.0.1:21080/ does not need Gmail or an app password. A shared server's sign-up policy remains a separate setting.

Configure SMTP when people need account-email verification and password recovery by email. This page is for the server operator who controls how dtxWiki starts; workspace ownership alone does not grant that access.

What changes when mail is enabled

Setup	Account behavior
Mail disabled, basic local HTTP	Email verification and email password recovery are unavailable. Follow Members and access for account and operator procedures.
Mail disabled, canonical HTTPS URL configured	The operator can provide an administrator-assisted one-time recovery link. SMTP is still optional.
SMTP and canonical HTTPS URL configured	Signed-in users can request email verification. Eligible active accounts with a verified address can request a password-reset email.

Adding a workspace member is separate and does not promise an invitation email. SMTP does not enable Google sign-in or an AI app's MCP connection.

An account-mail request is saved in an outbox, a sending queue. The worker sends it through the configured SMTP provider. Gmail receives the recipient address and message, including the one-time account link. See Privacy and safe sharing.

Prepare the server first

1. Confirm that the server is already reachable at its real HTTPS address. Set DTXWIKI_PUBLIC_BASE_URL to that address, such as https://wiki.example.com. This setting does not create a domain, certificate, or reverse proxy; follow Server deployment first.
2. Keep app and worker on the same installation, database, data directory, and session secret, so the worker can read the queued messages. An unrelated worker cannot replace it.
3. Choose a sender account you control and an account whose inbox you can check. Replace the placeholder addresses below.

Settings → Deployment → Identity & Recovery shows the provider, sender, canonical URL, redacted credential status, outbox counts, and last observed delivery. It displays operator commands; it is not an SMTP password editor or a test-email button. Apply settings through the process environment or production configuration, then restart both app and worker.

Gmail example

The main example uses smtp.gmail.com with 587 and STARTTLS. The alternative is 465 with SSL/TLS. dtxWiki requires exactly one transport mode. Google's SMTP protocol reference documents the host and ports.

Setting	Value
DTXWIKI_MAIL_PROVIDER	smtp
DTXWIKI_MAIL_FROM_ADDRESS	Your full Gmail address, for example your-gmail-address@gmail.com
DTXWIKI_SMTP_HOST	smtp.gmail.com
DTXWIKI_SMTP_USERNAME	The same full Gmail address
DTXWIKI_SMTP_PASSWORD	A Google app password for this application
DTXWIKI_PUBLIC_BASE_URL	Your existing dtxWiki HTTPS address

Secure connection	Port	DTXWIKI_SMTP_STARTTLS	DTXWIKI_SMTP_USE_SSL
STARTTLS	587	true	false
SSL/TLS from connection start	465	false	true

Create an app password

1. Sign in to the Google account that will send mail and enable 2-Step Verification.
2. Open Google Account → App passwords. Name the application dtxWiki SMTP and create a password.
3. Keep it in your approved secrets store and use it for SMTP, instead of your usual Google account password.

App passwords may be unavailable for work/school accounts, security-key-only 2-Step Verification, or Advanced Protection. Check policy or choose another allowed SMTP service; do not disable account protections. dtxWiki uses username/password SMTP authentication, not Gmail OAuth. Google revokes app passwords after an account-password change: replace the secret and restart both processes. Revoke unused app passwords. Google's app-password guide, Advanced Protection restrictions.

systemd: save production settings

These commands use the existing production installation's protected /etc/dtxwiki/dtxwiki.env. Run them in Bash on the server. Replace the HTTPS URL and sender first. Keep the provider none while changing transport settings, then select smtp last to avoid an invalid intermediate combination.

sudo dtxwiki config set DTXWIKI_MAIL_PROVIDER=none
sudo dtxwiki config set DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
sudo dtxwiki config set DTXWIKI_MAIL_FROM_ADDRESS=your-gmail-address@gmail.com
sudo dtxwiki config set DTXWIKI_SMTP_HOST=smtp.gmail.com
sudo dtxwiki config set DTXWIKI_SMTP_PORT=587
sudo dtxwiki config set DTXWIKI_SMTP_STARTTLS=true
sudo dtxwiki config set DTXWIKI_SMTP_USE_SSL=false
sudo dtxwiki config set DTXWIKI_SMTP_USERNAME=your-gmail-address@gmail.com
IFS= read -r -s -p 'Gmail app password: ' gmail_app_password
printf '\n'
sudo dtxwiki config set "DTXWIKI_SMTP_PASSWORD=$gmail_app_password" --i-understand
unset gmail_app_password
sudo dtxwiki config set DTXWIKI_MAIL_PROVIDER=smtp
sudo systemctl restart dtxwiki dtxwiki-worker

The hidden prompt keeps the literal password out of shell history. The existing CLI briefly passes the value as a process argument; use an operator-controlled terminal with command tracing disabled. Do not paste secrets into shared examples, issues, or screenshots. The password command requires --i-understand; config show redacts its stored value.

Writing configuration does not update running processes. After restarting both, check:

sudo dtxwiki config show
sudo systemctl status dtxwiki dtxwiki-worker --no-pager

Reopen Identity & Recovery. Its configured state checks settings, not whether Gmail accepted a message or a recipient received it. Complete the delivery check below.

For 465, set DTXWIKI_SMTP_PORT=465, DTXWIKI_SMTP_STARTTLS=false, and DTXWIKI_SMTP_USE_SSL=true while the provider is none, then select smtp and restart both services.

Manual starts: terminal environment

Use these examples only with an already working HTTPS endpoint. They affect the current terminal and do not persist production configuration. Stop the existing app and worker before starting them with new settings. Keep the existing data-directory and session-secret settings.

Choose the commands for your installation method. The environment examples below finish with the Python-installed app command; npm-only users should replace it with their row's app command and use the matching worker command in the second terminal. See Keep the server running.

Installation	App command	Worker command in the second terminal
Python tool installed with pipx or uv	dtxwiki --no-open	dtxwiki-worker run
npm/npx with uv	npx @dtxsuite/dtxwiki@0.1.2 serve --no-open	uvx --python 3.12 --from dtxwiki==0.1.2 dtxwiki-worker run
npm/npx with pipx	npx @dtxsuite/dtxwiki@0.1.2 serve --no-open	pipx run --spec dtxwiki==0.1.2 dtxwiki-worker run

Bash on Linux or macOS

export DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
export DTXWIKI_MAIL_PROVIDER=smtp
export DTXWIKI_MAIL_FROM_ADDRESS=your-gmail-address@gmail.com
export DTXWIKI_SMTP_HOST=smtp.gmail.com
export DTXWIKI_SMTP_PORT=587
export DTXWIKI_SMTP_STARTTLS=true
export DTXWIKI_SMTP_USE_SSL=false
export DTXWIKI_SMTP_USERNAME=your-gmail-address@gmail.com
IFS= read -r -s -p 'Gmail app password: ' gmail_app_password
printf '\n'
export DTXWIKI_SMTP_PASSWORD="$gmail_app_password"
unset gmail_app_password
dtxwiki --no-open

Open the server through HTTPS. In a second terminal, repeat the same environment assignments and hidden password prompt with the same data-directory and session-secret settings. Once the app is ready, run this instead of the last dtxwiki --no-open line:

dtxwiki-worker run

A new terminal does not inherit the first terminal's exports. Stop both processes with Ctrl+C in their own terminals. Clear the secret with unset DTXWIKI_SMTP_PASSWORD when finished; clearing a variable does not change an already-running process.

PowerShell for manual Windows use

$env:DTXWIKI_PUBLIC_BASE_URL = "https://wiki.example.com"
$env:DTXWIKI_MAIL_PROVIDER = "smtp"
$env:DTXWIKI_MAIL_FROM_ADDRESS = "your-gmail-address@gmail.com"
$env:DTXWIKI_SMTP_HOST = "smtp.gmail.com"
$env:DTXWIKI_SMTP_PORT = "587"
$env:DTXWIKI_SMTP_STARTTLS = "true"
$env:DTXWIKI_SMTP_USE_SSL = "false"
$env:DTXWIKI_SMTP_USERNAME = "your-gmail-address@gmail.com"
$gmailAppPassword = Read-Host "Gmail app password" -AsSecureString
$env:DTXWIKI_SMTP_PASSWORD = [System.Net.NetworkCredential]::new("", $gmailAppPassword).Password
Remove-Variable gmailAppPassword
dtxwiki --no-open

Use a second PowerShell window for the worker: repeat the same environment setup and prompt, then run dtxwiki-worker run instead of the last line. Preserve the same data-directory and session-secret settings. This is a manual-start example; official production hosting targets Linux. After stopping both processes, clear the secret with Remove-Item Env:DTXWIKI_SMTP_PASSWORD.

Docker Compose

In an existing production Compose installation, put the Gmail table's settings in the private infra/prod/.env. Enter the password in a protected editor or approved secrets workflow. Keep DTXWIKI_DOMAIN set to the working HTTPS domain; Compose derives the public URL from it. The released Compose file passes mail settings to both app and worker.

From that Compose directory, apply the changed environment:

docker compose up -d --force-recreate app worker

A simple container restart does not apply changed Compose environment values. Do not share .env or attach docker compose config output publicly; it can contain resolved secrets.

Confirm actual delivery

Check your own server with an account you control. The configuration examples are instructions, not a claim that external Gmail delivery has been tested for your installation.

1. Sign in to an active account whose inbox you can read. Open Account, then Verify email if the address is unverified.
2. Check inbox and spam folders. Open the newest verification message; confirm that its link uses your real dtxWiki HTTPS domain. Complete verification and check for Email verified on the account page.
3. As a server administrator, inspect Identity & Recovery: last observed delivery and queued/failed counts. Provider acceptance is useful evidence; also confirm arrival in the inbox.
4. If you test password recovery, use Forgot your password? for this verified account and complete the latest link. This changes the account: public self-service recovery revokes browser sessions and API/MCP/OAuth credentials. Reconnect that account's tools afterward.

The public reset response does not disclose whether an address is registered or eligible. A request-accepted message alone is not proof of sending. See Members and access for operator-assisted recovery and delivery choices.

Troubleshooting

What you see	Next check
No Verify email	SMTP and canonical HTTPS must be configured; an already-verified address needs no request.
No Google App passwords option	Check 2-Step Verification and account restrictions; choose another allowed provider if needed.
Gmail rejects authentication	Use the full sender address and app password. Changing the Google account password revokes earlier app passwords.
SMTP transport error	Choose 587 / STARTTLS true / SSL false, or 465 / STARTTLS false / SSL true.
Mail remains queued	Run the worker against the same database and data directory, with the same secret and SMTP environment. Restart both after changes.
Link points elsewhere or uses HTTP	Correct DTXWIKI_PUBLIC_BASE_URL, restart both processes, then request a new message.
Failed delivery or no inbox message	Check outbound SMTP-port access, credentials, provider restrictions, recipient address, and spam filtering. Use the newest message after correcting the cause.
Reset request accepted but no mail	The target must be an eligible active account with a verified address. Ask the operator to inspect recovery status.

To disable mail, set DTXWIKI_MAIL_PROVIDER=none in the configuration that starts both processes, then restart both. Revoke the unused Google app password. Mail-free use remains available; administrator-assisted links still require the canonical HTTPS URL.

---

Version evidence: mail settings, SMTP and outbox, account recovery, configuration CLI, worker, Compose environment.