How to Self-Host Wiki.js in 2026: Database Setup, TLS and Restore Tests

Most Wiki.js installation notes end at the first page load. That is too early: DB_HOST is localhost inside the container or TLS proxy headers are missing. A useful production test is more demanding — finish setup, create and revise a page, upload media, search for it and inspect version history after restart.

Wiki.js's role is straightforward: Markdown wiki with versioning and a modern editor. Its operational boundary includes more than the web process, so the dependency, stored state and public route all have to be named explicitly before real data arrives.

Draw the Wiki.js runtime boundary

The smallest responsible Wiki.js topology contains one private listener on 3000, an ingress route and a documented state boundary. The network contract for Wiki.js is a reachable Postgres, MySQL, MariaDB, MSSQL or SQLite database. Keep private endpoints on internal DNS, permit only required outbound calls and give Wiki.js a scoped service credential.

Validate the topology by asking a clean client to finish setup, create and revise a page, upload media, search for it and inspect version history after restart. Watch database response time, search indexing, media storage and authentication-provider latency while it runs. The result tells you whether the next improvement belongs in memory, storage, networking or a separate worker instead of encouraging arbitrary container sizing.

Design the Wiki.js restore before launch

No writable application state is expected inside the standard Wiki.js image. Preserve the database plus any local uploads and custom assets, including the pinned digest and reviewed route configuration, rather than backing up an empty container filesystem.

Create Wiki.js from scratch on another host and verify that pages, history, users, groups, media and navigation return and a known page remains searchable. If a separate database, room server or authentication layer is added, give that component its own explicit recovery owner. The Git-to-production guide shows how a reproducible artifact replaces a container backup.

Record the rebuild command and known-output test with the release. A stateless recovery plan succeeds by reproducing behavior from trusted inputs; it should not depend on copying an opaque running container.

Choose the Wiki.js trust boundary

A secure Wiki.js deployment starts by removing authority. Avoid keeping the setup screen exposed after the first administrator exists; instead, remove public access to setup, restrict administration and give the wiki database its own credentials.

Treat DB_PASS according to its Wiki.js role: keep sensitive values out of Git, document rotation effects and never substitute a public example in production. Restrict administrative routes, use private DNS for dependencies and review every bind mount. When logs are shipped centrally, filter secrets and private content before they leave the server.

What must pass before real Wiki.js data arrives

A production gate for Wiki.js should be executable by someone who did not build the deployment. Give that person the pinned version, a non-sensitive test account and this task: finish setup, create and revise a page, upload media, search for it and inspect version history after restart. If the instructions require undocumented shell access, the service is not yet operationally ready.

Repeat the gate after replacing only the container. Then restore the database plus any local uploads and custom assets into blank infrastructure and prove that pages, history, users, groups, media and navigation return and a known page remains searchable. Measure database response time, search indexing, media storage and authentication-provider latency during both successful runs; unexpected differences often reveal a missing cache, index, worker or data mount.

Add a failure drill: temporarily deny the test identity access to a reachable Postgres, MySQL, MariaDB, MSSQL or SQLite database. Wiki.js should emit a useful error, preserve existing state and recover when the valid condition returns. Save the timestamps and relevant log lines, with secrets redacted. That evidence becomes the reference for the next image or configuration change.

Start Wiki.js without hiding the moving parts

Keep the initial Wiki.js invocation reproducible enough to review in a pull request.

docker run -d \
  --name wiki-js \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e DB_PASS=replace-with-a-long-random-value \
  -e DB_TYPE=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_PORT=5432 \
  -e DB_USER=wiki \
  -e DB_NAME=wiki \
  ghcr.io/requarks/wiki:2

Do not rely on latest after real data exists. Capture the working digest, container user and mount ownership. Follow the application log through a complete test — finish setup, create and revise a page, upload media, search for it and inspect version history after restart — and note any migrations before putting the route behind production traffic.

Keep internal and external URLs straight

Treat the external Wiki.js URL as configuration that survives redeploys. First configure the site URL after routing the service through HTTPS; then route the hostname to port 3000 with the original host and scheme intact.

The deployment reachability checklist can prove that requests enter the container. After that point, the known failure — DB_HOST is localhost inside the container or TLS proxy headers are missing — should be investigated in Wiki.js, its state or its workload rather than in certificate automation.

Watch the workload, not only the container

Build dashboards around database response time, search indexing, media storage and authentication-provider latency. A CPU graph without that workload context cannot explain why Wiki.js is slow. Add a synthetic or scheduled check that tries to finish setup, create and revise a page, upload media, search for it and inspect version history after restart using harmless test data.

Before upgrading, account for this application-specific hazard: Wiki.js database migrations and authentication modules should be staged before moving to another release line. Restore a recent backup into an isolated deployment, run migrations there and compare behavior. If DB_HOST is localhost inside the container or TLS proxy headers are missing, inspect the boundary involved — public origin, storage or dependency — before touching unrelated settings.

Keep Wiki.js explicit while Dockup handles routing

Routing, certificates, service replacement and attached storage are reasonable automation targets. Dockup handles those for Wiki.js and can provision the related managed database or connect to services on a customer's own server.

What it should not invent is the Wiki.js trust policy. After deployment, configure the site URL after routing the service through HTTPS, enforce this boundary — remove public access to setup, restrict administration and give the wiki database its own credentials — and verify the result of this scenario: finish setup, create and revise a page, upload media, search for it and inspect version history after restart. The outcome is one-click infrastructure with an application-specific acceptance test.

Frequently asked questions

What does Wiki.js need for a production deployment?

Route the Wiki.js container on port 3000 through one HTTPS origin. The supporting network requirement is a reachable Postgres, MySQL, MariaDB, MSSQL or SQLite database. Do not call Wiki.js ready until you can finish setup, create and revise a page, upload media, search for it and inspect version history after restart.

Which Wiki.js data belongs in a backup?

The standard Wiki.js image has no required application-data mount. Preserve its deployment configuration and back up any connected state separately; recovery passes when pages, history, users, groups, media and navigation return and a known page remains searchable.

Does Wiki.js require HTTPS behind a reverse proxy?

Use HTTPS for the public Wiki.js origin and keep port 3000 on the internal route. Apply the Wiki.js setting correctly: configure the site URL after routing the service through HTTPS. For Wiki.js, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Wiki.js upgrade be tested?

Restore current Wiki.js state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because Wiki.js database migrations and authentication modules should be staged before moving to another release line. Keep the previous Wiki.js image until its data-migration and rollback boundary are understood.