Self-Hosting a Wiki with Wiki.js or BookStack on Raspberry Pi: Documentation and SOPs for Your Shop

Every shop accumulates knowledge that lives nowhere useful: the exact feeds and speeds that work for that one sheet of leftover acrylic, which M3 screw length actually fits the printer's X-axis bracket, the startup sequence for the CNC that you only remember because you've done it two hundred times. A sticky note on the machine works until it falls off. A folder of scattered text files works until you need the one file and can't remember what you named it. A self-hosted wiki, running on a Raspberry Pi that's already on all the time, gives that knowledge a real home — searchable, linked, and shared with anyone else who uses the shop, without relying on a cloud notes app you don't control.

Wiki.js vs BookStack: Which One Fits a Shop Wiki

Both are mature, actively developed, self-hosted wiki platforms with official Docker images and genuinely good Markdown editing — either is a reasonable choice, and the right one depends on how you think about organizing documentation.

Wiki.jsBookStack Organization modelFlexible page tree, tags, and full-text search; feels like a traditional wikiStrict Shelves → Books → Chapters → Pages hierarchy; feels like structured documentation EditorMarkdown, visual editor, or a block-based editor — your choice per pageMarkdown or WYSIWYG, consistent per instance Best forA loosely organized, fast-growing knowledge base where pages link to each other organicallyStructured SOPs and manuals you want organized like a binder of machine handbooks Resource use on a PiModerate — Node.js backendLight — PHP/MySQL stack, runs comfortably on a Pi 4

If your mental model for shop knowledge is "a page for everything, linked together as it grows," pick Wiki.js. If you think in terms of "one book per machine, with chapters for setup, maintenance, and troubleshooting," BookStack's hierarchy will feel more natural and will keep a growing shop wiki from turning into an unstructured pile of pages.

Installing Wiki.js with Docker Compose

mkdir -p ~/wikijs && cd ~/wikijs cat > docker-compose.yml <<'EOF' services: db: image: postgres:15-alpine environment: POSTGRES_DB: wiki POSTGRES_PASSWORD: changeme POSTGRES_USER: wikijs volumes: - ./db-data:/var/lib/postgresql/data restart: unless-stopped wiki: image: ghcr.io/requarks/wiki:2 depends_on: - db environment: DB_TYPE: postgres DB_HOST: db DB_PORT: 5432 DB_USER: wikijs DB_PASS: changeme DB_NAME: wiki ports: - "3000:3000" restart: unless-stopped EOF docker compose up -d

Change the database password from the placeholder before you bring the stack up for real, then open http://<your-pi-ip>:3000 and walk through the first-run setup wizard, which creates your admin account.

Installing BookStack with Docker Compose

mkdir -p ~/bookstack && cd ~/bookstack cat > docker-compose.yml <<'EOF' services: bookstack_db: image: mariadb:10.11 environment: MYSQL_ROOT_PASSWORD: changeme MYSQL_DATABASE: bookstack MYSQL_USER: bookstack MYSQL_PASSWORD: changeme volumes: - ./db-data:/var/lib/mysql restart: unless-stopped bookstack: image: lscr.io/linuxserver/bookstack depends_on: - bookstack_db environment: - DB_HOST=bookstack_db - DB_USER=bookstack - DB_PASS=changeme - DB_DATABASE=bookstack - APP_URL=http://changeme-your-pi-ip:6875 ports: - "6875:80" volumes: - ./data:/config restart: unless-stopped EOF docker compose up -d

Set APP_URL to your Pi's actual address or hostname before starting the stack — BookStack uses it to generate internal links, and getting it wrong after pages already exist means broken links until you fix it and clear cached pages.

Structuring a Shop Wiki That Actually Gets Used

The single biggest failure mode for a shop wiki isn't the software — it's that nobody updates it because finding the right page to edit feels like more effort than it's worth. A structure that keeps friction low:

• One top-level page or book per machine, named exactly what everyone already calls it ("the Ray5," not "Longer Ray5 20W Diode Laser Engraver"), so search finds it on the first try.
• A consistent template inside each machine page — Startup, Common Settings, Maintenance Schedule, Known Issues — so contributing feels like filling in a form rather than writing from scratch.
• A "scratch" or "quick notes" page per machine for the kind of thing that doesn't deserve its own section yet — jot it there first, promote it to a proper section later if it turns out to matter. This single change does more for adoption than any amount of structure, because it removes the excuse of "I don't know where this goes."
• Embed or link photos of jig setups, wiring, and fixture positions directly in the relevant page rather than in a separate photo folder — a wiki page with one clear photo of "clamp goes here" prevents more repeated questions than a paragraph of text describing the same thing.

Access Control for a Shared Shop or Makerspace

Both platforms support multiple user accounts with page- or space-level permissions, which matters the moment more than one person uses the shop. A reasonable default: everyone with shop access gets an editor account (documentation that only admins can edit tends to go stale fast), but lock down anything involving safety procedures, chemical handling, or machine lockout/tagout steps to admin-only editing with public read access, so that critical safety content can't be casually altered by someone correcting what they think is a typo.

Backups

For Wiki.js, back up both the Postgres db-data volume and any uploaded assets directory. For BookStack, back up the MariaDB db-data volume and the data config directory, which holds uploaded images and attachments. Either way, a shop wiki that's accumulated a year of hard-won settings and troubleshooting notes is exactly the kind of thing you do not want to discover you never backed up the day an SD card fails — fold it into the same Restic or Borg backup routine covering your other self-hosted services.

Closing Thoughts

A wiki only pays off if people actually write things down in it, and the biggest lever for that isn't picking the "better" platform — it's keeping the structure loose enough that adding a quick note takes less time than remembering it wrong next time. Start with just your most-used machine's page, get in the habit of updating it after you change a setting or fix a problem, and let the rest of the wiki grow from actual need rather than trying to document the whole shop on day one.