> ## Content Index
> Fetch the complete content index at: https://blog.coopnet.us/llms.txt
> Use this file to discover other available public pages before exploring further.

# Why I keep a house wiki, and why it runs on BookStack
- URL: https://blog.coopnet.us/why-i-keep-a-house-wiki/
- Published: 2026-11-13T15:34:01.000Z
- Updated: 2026-11-13T15:34:01.000Z
- Description: My house and lab notes were written for a tool, so nobody in the house could use them. I moved them into a selfhosted BookStack behind Authentik. What made it work: lock the book as well as the shelf, keep one list per thing, give API tokens an expiry, and count the tables in every dump.
- Author: Renstur
- Tags: services, bookstack, documentation, authentik, opinion

I keep a BookStack wiki for my house and my lab. Before it, that documentation lived in two places: my head, and a pile of notes my AI coding assistant kept for itself.

Both were useful to exactly one reader. Neither helped my family when the internet went down, and neither helped me when I couldn't remember which box did what and didn't want to open a chat to find out.

The wiki is selfhosted, and it's written for the people in the house as much as for me. I think it's worth running, though mostly not for the reason I set it up. There are also a few things I'd do differently if I started today.

## Notes written for a tool

The real reason the wiki exists is that my notes were written for a tool to read. They were accurate and dense, and nobody in the house could browse them. A runbook that only shows up when I ask the right question in the right session isn't much of a runbook.

The wiki fixed the reading problem. It also turned up a writing problem I didn't expect. Writing a page for someone else showed me where my own picture was wrong.

The best example was a page about reaching household services from outside the house. The first version was built around location: at home on the WiFi you can reach everything, away from home you can't. It read well. It was also backwards.

Home internet doesn't route through my overlay network at all. Only devices with the NetBird client do, and only if they're in a group that's allowed to reach that service. A laptop on the house WiFi without the client gets the same refusal as a phone on mobile data. A phone with the client works from a hotel.

I only caught it because I had to read the page the way a user would. It's keyed on the device now, and it says so.

## How it runs

The setup is boring on purpose. BookStack and MariaDB sit in one compose project, published through the NetBird reverse proxy so family can reach it away from home. Nothing gets in without logging in.

Login is Authentik over OIDC, with Authentik groups mapped to BookStack roles. Admins get admin, family gets an editor role, a read only role covers anyone who should look but not edit, and anonymous visitors get nothing useful. Group sync has a nasty trap with spaces in group names, which I wrote up in [Two of three group mappings worked](https://blog.coopnet.us/two-of-three-group-mappings-worked/). If you're mapping Authentik's default admin group, read that one first.

The content splits into two shelves. One is for the household: pages that start from the symptom, written for someone who isn't technical and is probably stressed. They say when something is working as intended, and who to ask when it isn't. One camera page explains which alerts it filters out on purpose. Quiet doesn't mean broken.

The other shelf is runbooks, admins only: publishing an internal service, running a service without root, keeping a customized fork updatable. Different readers, different writing.

## Lock the book, not just the shelf

Restricting the runbooks shelf to admins hides the shelf from everyone else. It doesn't hide the book on it.

Shelf permissions in BookStack don't cascade to the books on them. A book left inheriting keeps the normal role permissions, so it stays in the books list and in search for every role that can usually see books, even when its shelf is hidden. You have to lock the book itself.

The shelf's permissions page can copy its settings to every book on it in one go. It only copies once, so a book I add later needs the same treatment. Chapters and pages inherit from the book after that, so I don't need overrides on individual pages.

Checking permissions with an admin account or an admin API token only tells you what's configured. An admin sees everything either way. The real test is logging in as a role that shouldn't see the page and confirming it isn't there.

## Point at the list, don't copy it

The mistake I keep catching in my own pages is duplication. The login page listed six services. The access page listed 22\. Both claimed to be the list, and they'd drifted apart.

Now one page is the address book and everything else links to it. I did the same with the network gear. Instead of copying a device list into the wiki, the page explains how things are named in UniFi: switches and access points for where they're mounted, cameras for what they overlook. UniFi stays the source of truth, and the wiki teaches you how to read it. A copied list would have been out of date the first time something moved.

Corrections work the same way. I once fixed a set of wrong room names in Home Assistant and assumed that was the end of it. The wiki still had the old names weeks later. Now when I correct something in one system, I search the others for the same string.

## API tokens need an expiry date

I script a fair bit of the wiki through its REST API, with the header `Authorization: Token <token_id>:<token_secret>`. Two things surprised me.

If you leave the expiry blank when creating a token, BookStack gives it a lifetime of about a hundred years. I set a date every time now.

Tokens are also per user, and there's no API endpoint to list or rotate them. Rotation happens in the UI, and your account page only shows your own tokens. An admin can see someone else's by opening that user under Settings > Users. When I audited mine, an older token was sitting on an account it didn't belong to. So when I clean up, I walk every user.

The secret is shown once and stored hashed. If you don't copy both halves when you create it, that token is dead. Make a new one.

## The backup that was empty

Before the last BookStack update I took a database dump, saw a file, and carried on. It was empty.

The dump had failed, stderr went nowhere, and the only check I ran was that the gzip file was valid. An empty gzip is perfectly valid.

The root password in the database container's environment no longer matched the real one:

```console
$ docker exec bookstack-db sh -c 'mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases' | gzip > pre-update.sql.gz
Access denied for user 'root'@'localhost' (using password: YES)

```

Dumping with the application account works. Testing the archive told me nothing, so now I count tables:

```console
$ docker exec bookstack-db sh -c 'mariadb-dump -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" --single-transaction --no-tablespaces "$MYSQL_DATABASE"' | gzip > pre-update.sql.gz
$ zcat pre-update.sql.gz | grep -c '^CREATE TABLE'
41

```

If that prints zero, I have a file and no backup. BookStack v26.09.3 came out on November 11, 2026 as a security release, and a security release is exactly when I want a dump I've counted.

## Was it worth it

For me, yes. I set it up so other people could find things. The bigger payoff was that writing for them made me get things right. My wrong picture of remote access had lived in my head for a long time. It didn't survive being written down for someone else.

## What I'd tell myself

Start smaller. One page for each thing someone in the house might panic about, one admin book with the runbooks I'd want when something's down, permissions locked on the book, and a dump I've actually counted.

```tested-on
bookstack: v26.09.2 (Docker)
mariadb: 11
sign-in: Authentik OIDC with group sync

```