How to Self-Host Trilium Notes in 2026: Data Directory, WebSockets and Backups

A Trilium Notes container can be green while the job users care about is broken. For Trilium Notes, that hidden failure is usually that the data directory is mounted at the wrong path or is not writable. This guide treats “create linked notes, add an attachment and relation, search for them and verify revision history after restart” as the acceptance test and builds the deployment backward from that result.

Trilium Notes has a specific role in the stack: tree-shaped personal knowledge base. The production question is therefore not whether port 8080 answers once, but whether state, dependencies and the public address continue to agree after a restart, update and restore.

Map Trilium Notes before touching Docker

The Trilium Notes HTTP process listens on 8080; keep that port on the application network and publish only the platform route. The local runtime requirement is a durable data directory and enough memory for indexing. Validate it under the acceptance workload; an idle health check cannot prove that the resource is sufficient.

Write the boundary down as a short contract: who owns the requirement, which credential is used, what timeout is acceptable and how failure appears. Then run this transaction: create linked notes, add an attachment and relation, search for them and verify revision history after restart. Observe note indexing, attachment size, scripting and the growth of document.db during the run, because that workload gives a more useful starting size than an idle container.

Test Trilium Notes from outside the server

Expose one HTTPS hostname for Trilium Notes; keep raw port 8080 private. Publish the web UI through HTTPS with WebSockets preserved. This prevents browsers and API clients from learning two competing addresses.

From a clean client, run the known-good transaction and inspect the first failing request. Use the custom-domain guide when DNS or TLS is wrong. Treat “the data directory is mounted at the wrong path or is not writable” as a separate application diagnosis once the route is proven.

Launch Trilium Notes with observable defaults

A production-shaped launch is intentionally boring: named state, explicit port and no secret inside the image.

docker run -d \
  --name trilium-notes \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v trilium-notes-data:/home/node/trilium-data \
  -e TRILIUM_DATA_DIR=/home/node/trilium-data \
  triliumnext/notes:latest

The example is a baseline rather than a complete supporting stack. Confirm the local requirement before exposure: a durable data directory and enough memory for indexing. Check the effective mounts and listener, then try to create linked notes, add an attachment and relation, search for them and verify revision history after restart. Pin the working image before the next restart.

Watch the workload, not only the container

Observe the work Trilium Notes performs: note indexing, attachment size, scripting and the growth of document.db. Set limits with headroom for that work and avoid a liveness probe that competes with it. The operator check should still attempt to create linked notes, add an attachment and relation, search for them and verify revision history after restart on a schedule.

For updates, remember that TriliumNext migrations, scripts and theme extensions should be tested on a duplicate data directory. Deploy the candidate against a recovered copy and repeat the known test. If the data directory is mounted at the wrong path or is not writable, use runtime logs and the actual network request to find which assumption changed.

What must pass before real Trilium Notes data arrives

The release record for Trilium Notes needs facts, not “looks good.” Store the selected image digest, configuration checksum, public hostname and a timestamped result for: create linked notes, add an attachment and relation, search for them and verify revision history after restart. Use non-production sample data so the check can run after every deployment.

Prove two lifecycle events separately. A container replacement must preserve normal operation; a clean recovery must show that notes, relations, attachments, attributes and revisions return and the known search finds the same note. While the checks run, measure note indexing, attachment size, scripting and the growth of document.db and retain the result as the expected envelope for this version.

Test a denied or invalid condition as well: submit harmless input near the resource or format limit associated with this boundary: the data directory is mounted at the wrong path or is not writable. Trilium Notes should fail in a diagnosable way and should not overwrite healthy state. Return the valid condition, rerun the sample and attach the relevant redacted logs. Those artifacts give a future rollback decision concrete evidence.

Back up the state Trilium Notes cannot recreate

Define recovery point and recovery time for Trilium Notes in terms of document.db, attachments, revisions and configuration. Mount /home/node/trilium-data before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. A named volume solves redeploy persistence; it does not solve compromise or server loss.

Build a clean restore environment, use the same pinned application version and prove that notes, relations, attachments, attributes and revisions return and the known search finds the same note. Record commands, ownership fixes and elapsed time. The backup guide is a useful standard: a backup is trusted after restoration, not after upload.

Choose the Trilium Notes trust boundary

Close the bootstrap window as soon as the first trusted administrator exists. Trilium Notes's concrete trap is exposing a personal knowledge base without a strong login; the safer boundary is to treat the notebook as private data, require strong login and expose no broader filesystem than its data directory.

TRILIUM_DATA_DIR controls behavior rather than confidentiality; validate its type and value, and store genuine Trilium Notes credentials separately. Private networking should carry dependency credentials, and roles inside Trilium Notes should grant the smallest useful action. Keep sensitive request bodies and provider responses out of routine logs.

What Dockup should automate for Trilium Notes

For Trilium Notes, Dockup can create the route and TLS certificate, preserve mounts, deliver secrets and place a durable data directory and enough memory for indexing on private networking while deploying to either Dockup or attached servers.

The release gate is still the concrete Trilium Notes transaction: create linked notes, add an attachment and relation, search for them and verify revision history after restart. Also verify the restore condition — notes, relations, attachments, attributes and revisions return and the known search finds the same note. Those two checks show whether the deployment works and whether it can be recovered.

Frequently asked questions

What does Trilium Notes need for a production deployment?

Route the Trilium Notes container on port 8080 through one HTTPS origin. The local runtime requirement is a durable data directory and enough memory for indexing. Do not call Trilium Notes ready until you can create linked notes, add an attachment and relation, search for them and verify revision history after restart.

Which Trilium Notes data belongs in a backup?

Persist /home/node/trilium-data and include document.db, attachments, revisions and configuration in the same recovery manifest. A clean Trilium Notes restore passes only when notes, relations, attachments, attributes and revisions return and the known search finds the same note.

Does Trilium Notes require HTTPS behind a reverse proxy?

Use HTTPS for the public Trilium Notes origin and keep port 8080 on the internal route. Apply the Trilium Notes setting correctly: publish the web UI through HTTPS with WebSockets preserved. For Trilium Notes, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Trilium Notes upgrade be tested?

Restore current Trilium Notes state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because TriliumNext migrations, scripts and theme extensions should be tested on a duplicate data directory. Keep the previous Trilium Notes image until its data-migration and rollback boundary are understood.