Why#
There is a version of this project where documentation is an afterthought — something you write after the infrastructure is stable, when there is time. That version produces systems that work until the person who built them is unavailable, and then quietly stops working.
HomeStack was always going to need a wiki. Not for external readers, but for the family. For the day when my partner needs to find something and I am not there to explain where it is. For the day when a child asks what the server in the office actually does. For the day when someone needs to restore a backup and the documentation is the difference between a procedure and a guess.
There is a parallel question about financial data. Every bank transaction I have ever made is stored in a database I do not control, in a format I cannot export cleanly, subject to terms I did not negotiate. For most people that is an invisible arrangement. I had started to find it uncomfortable — not because anything had gone wrong, but because I had no alternative. This phase was the beginning of building one.
Family#
The wiki went live, accessible from outside the house, login via the same account used for everything else on the stack. I showed my partner. The reaction was different from the password manager — less “hm” and more genuine interest. A place to put things. Documents, notes, shared information. Something that feels like shared infrastructure rather than a technical experiment.
The honest answer is that Outline was mostly empty. Three spaces, fourteen collections, placeholder titles. The structure was there. The content was not. A wiki without content is a very organised empty room.
But the room exists now. That is enough for this phase.
Tech#
Before the tools: a word on environments. HomeStack runs on three separate stages. The Dev environment is a Raspberry Pi in my home office — the real server, where everything gets built and tested with real configuration but no family data yet. The Lab is a temporary cloud server I rent by the hour for experiments that might break things — isolated, disposable, no consequences if something goes wrong. Prod is where the family lives, eventually. The financial tool evaluation happened entirely in the Lab. Whatever conclusions came out of it would inform what gets built on Dev.
The URL migration was supposed to be straightforward. All external services had been running on my self labeled ‘development’ node. Now that the wiki and password manager were live externally, the OIDC configuration needed to follow. Change the redirect URIs, update the environment variables, reload the containers.
What actually happened: the URL existed in six different places. The Authentik provider redirect URI. The service environment variables. The Caddy configuration. The Cloudflare tunnel. The Docker extra_hosts. And — the one I did not anticipate — the sso_users table in the Vaultwarden database, where SSO identifiers are stored as strings. Changing the URL broke Vaultwarden logins for all users because the stored identifiers no longer matched the new authority URL.
The fix required a direct SQL UPDATE on the database, followed by deleting and recreating all Vaultwarden users via the admin panel. It worked. The lesson was that OIDC is not a configuration layer — it is a dependency chain, and URL changes propagate in ways that are not always visible until something breaks.
The financial tool evaluation ran in parallel. Firefly III was the leading candidate — well-maintained, feature-rich, widely used in the self-hosting community. It failed on one test: it has its own OAuth server but is not a native OIDC client. Integrating it with Authentik would require oauth2-proxy as a middleware container. One extra container, one extra failure point, one more thing to maintain — and a workaround rather than a proper integration. Every public-facing service in this stack needs to be a native OIDC client. Firefly is not. That was enough.
The chosen route — a custom PostgreSQL schema with Metabase as the visualisation layer — is more work. It is also the only option that gives complete control over the data model, supports forecasting without workarounds, and integrates cleanly with Authentik. The data model started as a practical schema and grew into something more considered: polymorphic ownership, validity periods, explicit reliability attributes, a Rules as Code approach for fiscal logic. Forty entities on paper. Eleven for the first implementation.
Project#
Two tracks running simultaneously is a different kind of complexity than one track with problems. The wiki track was mostly execution — deploy, configure, migrate, test. The financial track was mostly thinking — evaluate, reject, design, scope. Both finished in the same week.
The Lab was cleaned up completely after the Firefly evaluation. All containers, volumes, and networks removed. This matters more than it sounds. A Lab that accumulates state becomes a source of confusion — you stop knowing what is running, what is a test, what is real. Cleanup is not housekeeping. It is part of the discipline.
One observation from this phase: the moment you have a wiki, you start to notice everything that is not documented. The decision records, the implementation plans, the project logs — all of that was already there. But the procedures. The runbooks. The “here is what to do if the server stops responding at 2am” documents. Those were still missing.
They are still missing. That is a known gap, not a forgotten one.