Docmost and the Self-Hosted Wiki Question

Every homelab reaches a point where the knowledge stops fitting in your head. Mine hit that wall the day I spent forty minutes rediscovering which container held the reverse proxy config, having written that answer down eight months earlier in a place I could no longer name. The notes existed. They were scattered across a README.md in a repo I had renamed, a text file on the desktop of a machine I had since reinstalled, and a browser bookmark pointing at a forum thread that had 404’d.

So I did what everyone does: I went looking for a wiki. And I discovered that the self-hosted wiki category is one of the strangest corners of open source — enormously well served and simultaneously unsatisfying. Docmost is the newest entrant, it has been public for a matter of months, and it is worth talking about precisely because it makes a different bet from everything that came before it.

Why the Existing Wikis Never Quite Fit

Understanding Docmost requires understanding what it is reacting against, so a quick tour of the incumbents.

DokuWiki stores pages as flat files on disk and needs no database at all. That is a genuine engineering achievement and it will still be running in 2040. It also has a markup syntax from another era and an editing experience that assumes you enjoy typing ====== Heading ======.

MediaWiki is what Wikipedia runs, which tells you both that it scales and that it was designed for an encyclopaedia edited by strangers. Setting it up for six pages about your NAS is like hiring a shipping company to move a sofa.

BookStack is the sensible one. PHP and Laravel, a rigid Shelves → Books → Chapters → Pages hierarchy, a WYSIWYG editor that works, and permissions that make sense. I ran it for a year and my complaint is structural: that hierarchy is brilliant when your content is genuinely book-shaped and irritating when it is a loose mesh of interlinked facts.

Wiki.js looked gorgeous and offered git sync, which is exactly what a person like me wants — pages as markdown files in a repo, with a web UI over the top. In practice the v2 codebase has been in maintenance limbo for a long while, with a promised v3 rewrite perpetually on the horizon. Adopting software whose maintainer has publicly moved on is a decision you make once.

Outline is the closest thing to a polished commercial product in the free tier of this space, and it is genuinely lovely. Its historical catch has been authentication: it was built for teams with an identity provider, so a homelab either wires up an OIDC flow or goes without. That is fine if you already run Authelia or Authentik — less fine as a first wiki.

Docmost lands in that gap. It is AGPL-licensed, it is aimed squarely at the Confluence-replacement niche, and its headline feature is the one nobody else in the free tier offers properly.

What Docmost Actually Does

The stack is NestJS on the backend, React on the front, Postgres for data and Redis for coordination. That Redis dependency is the tell: Docmost does real-time collaborative editing. Two people in the same page, two cursors, no lock contention, no “someone else is editing this” banner. It uses a CRDT under the hood, which is the same family of technology behind Google Docs’ conflict resolution.

The content model is Spaces containing Pages, and pages nest. That is it. No shelves, no books, no chapters. A space is a permission boundary and a browsing root, and everything below it is a tree you can drag around. After a year of BookStack’s four levels, the freedom felt slightly illicit.

The editor is block-based, in the Notion lineage — type / and pick a heading, a table, a callout, a code block. It speaks markdown shortcuts, so ## still becomes a heading and a backtick still wraps inline code, which matters more than it sounds when your muscle memory is fifteen years deep.

Search is Postgres full-text search rather than a bolted-on Elasticsearch, which is the correct decision for anything under a few thousand pages and saves you a JVM.

Standing It Up

The compose file is unremarkable in the best way. Three services, one volume for uploads, and one genuine footgun.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: 'https://wiki.mylab.local'
      APP_SECRET: '${APP_SECRET}'
      DATABASE_URL: 'postgresql://docmost:${DB_PASSWORD}@db:5432/docmost?schema=public'
      REDIS_URL: 'redis://redis:6379'
      STORAGE_DRIVER: 'local'
    ports:
      - '3000:3000'
    restart: unless-stopped
    volumes:
      - docmost_data:/app/data/storage

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: '${DB_PASSWORD}'
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data

  redis:
    image: redis:7.2-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  docmost_data:
  db_data:
  redis_data:

The footgun is APP_URL. Docmost builds its invite links, its websocket endpoint and its asset paths from that value, so if you set it to http://192.168.1.50:3000 for testing and later put a reverse proxy in front, the collaborative editing silently stops working — the page loads, and your typing simply never syncs. Set it to the final URL from the beginning.

Generate the secret properly rather than typing something memorable:

1
2
3

openssl rand -hex 32 > .app_secret
printf 'APP_SECRET=%s\n' "$(cat .app_secret)" >> .env
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" >> .env

The proxy side needs websocket upgrade headers or the whole collaboration layer dies quietly. If you are on Traefik or NGINX Proxy Manager, this is the box you must tick — I covered the trade-offs of both in the reverse proxy comparison. A minimal Caddy front door looks like this and needs nothing special, because Caddy handles upgrades by default:

1
2
3

wiki.mylab.local {
    reverse_proxy localhost:3000
}

First run creates a workspace and an admin account through the browser. Registration is closed after that unless you open it, which is the right default for a service reachable from anywhere.

Troubleshooting the Three Things That Will Bite You

Websockets fail and edits vanish. Symptom: the page renders, you type, nothing persists, and a refresh shows the old content. Check the browser console for a failed upgrade on /ws or similar. The two causes are a proxy that strips Upgrade/Connection headers and an APP_URL that does not match the address in your browser bar. Confirm the container itself is fine with a direct hit:

1
2

docker compose logs -f docmost | grep -i -E 'websocket|redis|error'
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/health

Redis is gone and nothing says so loudly. Docmost tolerates a missing Redis for basic page loads long enough for you to blame the wrong component. If collaboration is broken and the proxy is innocent, check Redis first:

1

docker compose exec redis redis-cli ping

Uploads land somewhere you did not expect. With STORAGE_DRIVER=local, attachments go under the container’s storage path. If you skipped the named volume, every attachment you have ever added evaporates on the next image pull. Ask me how I know. Point that volume at real storage and put it in your backup set — the same set that already holds your Postgres dumps, because a wiki with no attachments is a wiki full of broken image icons. If you have no such set yet, the 3-2-1 rule is the place to start, and a dump line in cron is thirty seconds of work:

1

docker compose exec -T db pg_dump -U docmost docmost | zstd -19 > "/backup/docmost-$(date +%F).sql.zst"

Where It Is Genuinely Thin

Docmost has been public for months, and it shows in the places you would expect.

Import is the big one. Moving an existing corpus in from Confluence or Notion is currently a manual affair, and “manual” for a few hundred pages means a weekend you will resent. If you have an incumbent wiki with real history in it, that history is the whole reason you have a wiki, and a migration path is a hard requirement rather than a nice-to-have.

The extension surface is small. BookStack has years of accumulated integrations and a mature LDAP/SAML story. Docmost’s auth is currently local accounts and invitations, which suits a household and frustrates anyone who has already centralised their identity.

Page history exists and works, and it is not git. There is no world where I git log my wiki, which for a certain kind of person is the single feature that would decide the argument.

And it is young. Young software in your homelab is a hobby; young software holding the only copy of your disaster-recovery notes is a risk. The AGPL licence and the Postgres backend mean your data is recoverable by hand if the project stalls, which is genuine insurance, though “recoverable by hand” is a sentence best kept theoretical.

The Question Behind the Question

Here is the thing I actually want to say, having run this experiment for a few weeks.

What most homelabs are missing is the habit of writing things down. Installing Postgres does nothing for that habit. I have watched myself — and half the people I know in this hobby — treat “choose the documentation platform” as productive work while the documentation itself stays unwritten. It is the most comfortable form of technical debt there is, because it feels like maintenance.

The honest test is whether you already have notes that are scattered. If you have twenty markdown files in three repos and you keep losing them, a wiki consolidates a real thing that exists. If you have nothing written down, a wiki gives you an empty database and a fresh excuse.

The second honest test is whether anyone else edits. Real-time collaboration is Docmost’s whole differentiator, and if you are a party of one it is an elegant solution to a problem you do not have. My household has two people who touch the network documentation, and even we have never once been in the same page simultaneously.

What I Actually Ended Up Writing In It

Since the platform argument is the fun part and the content is the work, a note on the content.

Four pages carry ninety per cent of the value in my workspace, and none of them are the ones I expected to write.

The first is a plain list of every service, the machine it lives on, the port it answers on, and one sentence on what breaks if it stops. No diagrams. That page has saved me more time than everything else combined, because the question I actually ask at 11pm is “where does this thing live”, never “what is my network architecture”.

The second is a decisions log, appended to and never edited. One line per entry, dated: what I changed, and why I chose it over the obvious alternative. Six months later this is the only artefact that stops me re-litigating a settled argument with myself. Git history theoretically contains this information; git history in practice contains “fix compose” thirty times.

The third is the restore runbook — the exact commands, in order, to get from a dead disk to a working service, written on a day when nothing was on fire. This one belongs somewhere that survives the thing you are recovering from, which means a printed copy or a file on a laptop, because a recovery runbook stored exclusively in the wiki running on the dead machine is a joke with a delayed punchline.

The fourth is a graveyard: things I tried and abandoned, with the reason. It stops me rediscovering the same dead end every eighteen months.

Everything else I wrote was theatre. The elaborate onboarding page nobody reads, the tagging taxonomy I designed before I had fifty pages, the template system — all of it is effort spent to avoid the four pages above. Docmost’s block editor makes writing these pleasant enough that the friction argument disappears, which is a real endorsement, and it is also the point at which the software has done everything software can do.

Verdict

Docmost is the most promising thing to happen to self-hosted wikis in a while, and the block editor plus flat spaces model is a genuinely better fit for homelab knowledge than BookStack’s rigid hierarchy. If you are starting fresh, you want a modern editor, you have two or more people writing, and you are comfortable running a young project on top of Postgres you already know how to back up, install it this weekend. It will not disappoint you.

If you have an existing wiki with years of pages in it, wait. The import story has to mature before the migration maths works, and BookStack will keep doing its job faithfully in the meantime.

And if you are one person with no notes, skip the whole category. Make a docs/ directory in the repo where your compose files already live, write the reverse proxy config down in it today, and revisit this post when that directory has thirty files and you cannot find anything. That is the version of me who actually needed a wiki, and it took eight months and forty wasted minutes to arrive.