A single-machine homelab: 34 running containers in 13 active Docker Compose
projects. It runs on Docker Engine on a native Linux host, kimmain. Four
systemd timers and a few host services do the work that sits outside Docker.
| OS | Zorin OS 18.1 (Ubuntu 24.04 base), kernel 7.0 |
| Hardware | ASUS EX-A320M-GAMING, AMD Ryzen 5 5500 (6C/12T), 32 GB RAM (31 GiB usable), NVIDIA GTX 1050 Ti 4 GB |
| Container runtime | Docker Engine 29.9.2, Compose v5.6.1, overlayfs, cgroups v2 |
| Disks | 256 GB NVMe (OS and all Docker volumes), 240 GB SATA SSD /mnt/d, 1 TB HDD /mnt/e, 1 TB USB HDD /mnt/backup |
| Remote access | Tailscale (tailnet only). Nothing private is reachable from the internet. |
| Documented state | Audited on the live host on 2026-10-26 |
Until 2026-10-23 the same workload ran on Windows 11 with Docker Desktop and the WSL2 backend. That migration is recorded in docs/reference/linux-migration-2026-10.md.
The system does five separate jobs, and its design comes from keeping them apart:
- Private services for one household: files, passwords, workflow automation, monitoring and container management. They are reachable only over the Tailscale tailnet.
- Public game servers: a modded Fabric Minecraft server (Season 2, 163 mod jars) and a vanilla-client Valheim server for a small group of friends.
- Public web: the Minecraft community website and the Postiz social media scheduler. Both sit behind their own reverse proxy, which has no route to anything private.
- Automation: social posting from a dropped-files queue, Discord status and chat bridges, dynamic DNS, availability alerts and a private Telegram assistant backed by a local LLM.
- Backups: seven backup sidecars and Valheim's built-in archiver turn live data into files. One nightly restic run copies those files, the primary data and a save-paused snapshot of the live Minecraft world to an external drive.
There are two independent front doors, and they never touch. That is the most important fact about this system.
flowchart LR
subgraph internet [Public internet]
players[Minecraft players]
vplayers[Valheim players]
visitors[Website visitors, Meta and TikTok fetchers]
end
subgraph tailnet [Tailscale tailnet]
devices[Owner's devices only]
end
players -->|"tcp 25565, udp 24454"| mc[mc-server]
vplayers -->|"udp 2456-2457"| vh[valheim-server]
visitors -->|"tcp 80/443, udp 443 on the LAN address"| caddy[mcweb-caddy]
devices -->|"tcp 443 on the tailnet address"| npm[nginx-proxy-manager]
caddy -->|mc.nhako.com| web[mcweb-web]
caddy -->|postiz.nhako.com| pz[postiz]
npm --> nc[Nextcloud]
npm --> vw[Vaultwarden]
npm --> pt[Portainer]
npm --> n8n[n8n]
npm --> bz[Beszel]
classDef pub fill:#7a2020,stroke:#d05555,color:#fff
classDef priv fill:#1d3f6b,stroke:#5590d0,color:#fff
class mc,vh,caddy,web,pz pub
class npm,nc,vw,pt,n8n,bz priv
The red path is public and the blue path is private. No process on the red path has a network route to any process on the blue path. Separate Docker networks and separate bind addresses enforce this. It does not depend on an access list that someone has to keep correct. docs/01-architecture.md explains this in full.
Every container uses restart: unless-stopped. "Published" lists only ports
bound on the host. Everything else is reachable only over Docker networks.
| Container | Image | Project | Published | Purpose |
|---|---|---|---|---|
npm |
jc21/nginx-proxy-manager:2.15.1 |
npm | <TAILNET_IP>:80,443, 127.0.0.1:81 |
TLS (one *.nhako.com wildcard) and reverse proxy for every private service |
vaultwarden |
vaultwarden/server:1.37.2-alpine |
vaultwarden | none | Password manager (vault.nhako.com) |
vaultwarden-backup |
alpine:latest |
vaultwarden | none | Daily SQLite .backup plus attachments and keys |
nextcloud |
nextcloud-previews:34.0.5-apache (built locally) |
nextcloud | none | Files, calendar, contacts, notes, tasks (cloud.nhako.com) |
nextcloud-cron |
nextcloud-previews:34.0.5-apache |
nextcloud | none | cron.php every 5 min, preview pre-generation every 10 min |
nextcloud-db |
postgres:17-alpine |
nextcloud | none | Nextcloud database |
nextcloud-redis |
valkey/valkey:8-alpine |
nextcloud | none | File locking and memory cache |
nextcloud-db-backup |
postgres:17-alpine |
nextcloud | none | Daily pg_dump, keeps 7 |
portainer |
portainer/portainer-ce:lts |
portainer | none | Container management UI (portainer.nhako.com) |
n8n |
n8nio/n8n:2.44.6 |
n8n | none | Workflow automation (n8n.nhako.com) |
n8n-db |
postgres:17-alpine |
n8n | none | n8n database |
n8n-db-backup |
postgres:17-alpine |
n8n | none | Daily pg_dump, keeps 7 |
beszel |
henrygd/beszel:0.21.1 |
beszel | 127.0.0.1:8090 |
Monitoring hub (beszel.nhako.com) |
beszel-agent |
henrygd/beszel-agent:0.21.1 |
beszel | host network | Host and per-container metrics |
| Container | Image | Project | Published | Purpose |
|---|---|---|---|---|
mc-server |
itzg/minecraft-server:java25 |
minecraft | 0.0.0.0:25565/tcp, 0.0.0.0:24454/udp |
Fabric server, Minecraft 26.2, see 07 Minecraft |
mc-backup |
itzg/mc-backup |
minecraft | none | World archive every 6 h, kept 7 days |
valheim-server |
ghcr.io/community-valheim-tools/valheim-server:latest |
valheim | 0.0.0.0:2456-2457/udp |
Valheim dedicated server, see 10 Valheim |
mcweb-caddy |
caddy:2-alpine |
mcweb | <LAN_IP>:80/tcp,443/tcp,443/udp |
Public TLS for exactly two hostnames: mc.nhako.com and postiz.nhako.com |
mcweb-web |
mcweb-web:local |
mcweb | none | Next.js community site |
mcweb-collector |
mcweb-collector:local |
mcweb | none | Reads the game server and writes Postgres |
mcweb-db |
postgres:17-alpine |
mcweb | none | The only long-term store of game history |
mcweb-db-backup |
postgres:17-alpine |
mcweb | none | Daily pg_dump, keeps 7 |
postiz |
ghcr.io/gitroomhq/postiz-app:latest |
postiz | none | Social media scheduler, see 11 Postiz |
postiz-db |
postgres:17-alpine |
postiz | none | Postiz database |
postiz-redis |
valkey/valkey:8-alpine |
postiz | none | Postiz queue and cache |
postiz-temporal |
temporalio/auto-setup:1.28.1 |
postiz | none | Workflow engine Postiz schedules through |
postiz-temporal-db |
postgres:16-alpine |
postiz | none | Temporal persistence |
postiz-temporal-es |
elasticsearch:7.17.27 |
postiz | none | Temporal visibility store |
postiz-db-backup |
postgres:17-alpine |
postiz | none | Daily pg_dump, keeps 7 |
postiz-autoposter |
node:22-alpine |
postiz | none | Books dropped files into posting slots |
| Container | Image | Project | Published | Purpose |
|---|---|---|---|---|
discord-status |
node:22-alpine |
discord-status | none | Discord bot presence with player counts, and the Valheim chat bridge, see 14 Discord |
nhako |
nhako:local |
nhako-bot | none | Private Telegram assistant, see 15 Nhako |
nhako-docker-proxy |
wollomatic/socket-proxy:1 |
nhako-bot | none | Allow-listed Docker socket proxy for nhako |
volume-backup |
postgres:17-alpine |
backup | none | Daily tar of five named volumes, keeps 3 |
These are kept for history in retired/. Their containers still exist
on the host in Created state and do not run.
| Container | Project | Retired |
|---|---|---|
homepage, homepage-socket-proxy |
homepage | 2026-10-23 |
rustdesk-hbbs, rustdesk-hbbr |
rustdesk | 2026-10-23 |
PairDrop (removed 2026-10-05) and a second Minecraft server (removed 2026-10-24) no longer exist anywhere on the host.
| Component | Kind | Document |
|---|---|---|
minecraft-dynamic-dns.timer |
systemd timer, every minute | 09 Host tasks |
minecraft-discord-notify.timer |
systemd timer, every minute | 09 Host tasks |
minecraft-monthly-poll.timer |
systemd timer, Saturdays 10:00 | 09 Host tasks |
restic-backup.timer |
systemd timer, daily 03:30, includes the mc_world snapshot |
04 Backup and recovery |
| Ollama | host service, *:11434 |
16 Host services |
Samba KIMNAS |
host service, LAN and tailnet | 16 Host services |
| OpenSSH, ufw, Tailscale | host services | 16 Host services |
| Document | What it covers |
|---|---|
| 01 Architecture | The two front doors, trust boundaries, project boundaries, boot order |
| 02 Storage | Drive roles, mounts, Docker volumes versus bind mounts, sizes |
| 03 Networking | Every Docker network, the full port and listener map, DNS, TLS, router |
| 04 Backup and recovery | The sidecars, restic, retention, restore runbooks |
| 05 Security | Exposure, Docker socket holders, secret handling, host hardening |
| 06 Operations | Runbook, health checks, updates, logs, power-cut behaviour |
| 07 Minecraft | The game stack: mods, JVM, world volume, backups, scripts |
| 08 mcweb | The website: Caddy, collector jobs, schema, GetGudLink mod |
| 09 Host tasks | The four systemd timers and the scripts they run |
| 10 Valheim | The Valheim server: exposure, DNS, Discord bridge, backups, sizing |
| 11 Postiz | The social scheduler, its public route and the autoposter |
| 12 n8n | Workflow automation |
| 13 Beszel | Monitoring hub and agent |
| 14 Discord | Every Discord integration and how they share credentials |
| 15 Nhako assistant | The Telegram assistant and its Docker access |
| 16 Host services | Ollama, Samba, SSH, ufw, Tailscale, updates, SMART |
| 17 Known gaps | Open risks and pending fixes found by the 2026-10-26 audit |
Mermaid sources for every diagram are in docs/diagrams/. Dated build logs, written while each part was assembled, are in docs/reference/. They are history, not current documentation. They hold the measurements and abandoned approaches behind settings that would otherwise look arbitrary.
Homelab26/
stack/ compose projects that live under /mnt/e/DockerData/stack
npm/ reverse proxy and TLS for the tailnet
vaultwarden/ password manager and its backup sidecar
nextcloud/ app (custom image), postgres, valkey, cron, db backup
portainer/ container management
n8n/ workflow automation, postgres, db backup
beszel/ monitoring hub and agent
postiz/ social scheduler, Temporal, autoposter, db backup
discord-status/ Discord presence bot and Valheim chat bridge
valheim/ Valheim server, Discord hooks, BepInEx chat plugin source
backup/ named-volume tar sidecar and the restic driver script
minecraft/ the game server compose file, scripts and datapacks
mcweb/ the website: Caddy, Next.js, collector, Postgres,
the GetGudLink Fabric mod, and the SQL migrations
host/ systemd units, daemon.json, sysctl, smb.conf, fstab
retired/ homepage and rustdesk, kept for history
docs/ everything listed above
On the host, these directories are split across two drives. Random I/O goes on the SSD and bulk data on the HDD:
| Repo path | Live path | Drive |
|---|---|---|
stack/ |
/mnt/e/DockerData/stack/ |
HDD |
minecraft/ |
/mnt/d/DockerData/minecraft/ |
SSD |
mcweb/ |
/mnt/d/DockerData/mcweb/ |
SSD |
host/systemd/ |
/etc/systemd/system/ |
NVMe |
host/docker/daemon.json |
/etc/docker/daemon.json |
NVMe |
host/sysctl/ |
/etc/sysctl.d/ |
NVMe |
host/samba/smb.conf |
/etc/samba/smb.conf |
NVMe |
The Nhako assistant's compose project lives with its own source code, outside
this tree, in /mnt/d/Edrive/Hakim/Projects/KimProjects/Nhako-Bot/. It is
documented in docs/15-nhako-assistant.md but not
mirrored here.
docs/02-storage.md explains the drive split.
Every project is independent. There is no top-level compose file, on purpose: restarting the website must never be able to restart the game server.
Shared networks and volumes set the order. edge must exist before anything
joins it, and it must have its original subnet, because Nextcloud trusts
172.18.0.0/16 as its proxy range:
docker network create --subnet 172.18.0.0/16 edgeThe world volumes are external and must exist before their stacks start:
docker volume create mc_world && docker volume create valheim_worldsThen bring the stacks up in this order. Each stack needs its .env created from
.env.example first; see Secrets.
stack/npm: everything private is reached through it.stack/vaultwarden,stack/nextcloud,stack/portainer,stack/n8n.minecraft/: createsminecraft_default, which mcweb joins.mcweb/: createsmcweb_postiz, which Postiz joins.stack/postiz.stack/valheim,stack/discord-status.stack/beszel: the agent sits behind a compose profile:docker compose --profile agent up -d
stack/backup.
Each of these starts with the same command from its own directory:
docker compose up -dstack/nextcloud builds its image the first time (build: ./build).
The host side (systemd units, Samba, sysctl) is installed from host/. See
docs/09-host-tasks.md and
docs/16-host-services.md.
No credential is in this repository. Every file that holds one is listed in
.gitignore and shipped as a .example sibling. The sibling has the same keys
and the same comments, but placeholder values.
| You must create | From | Holds |
|---|---|---|
stack/npm/.env |
.env.example |
Tailscale bind address |
stack/vaultwarden/vaultwarden.env |
vaultwarden.env.example |
argon2id admin token (every $ written as $$) |
stack/nextcloud/.env |
.env.example |
Postgres, Valkey and seed-admin passwords |
stack/n8n/.env |
.env.example |
Postgres password, N8N_ENCRYPTION_KEY |
stack/beszel/.env |
.env.example |
Agent key and token issued by the hub |
stack/postiz/.env |
.env.example |
JWT secret, two DB passwords, Meta and TikTok app credentials, Public API key, optional webhook |
stack/discord-status/.env |
.env.example |
#valheim-chat webhook |
stack/valheim/.env |
.env.example |
Join password, Discord webhook |
stack/backup/.restic-password |
create by hand, mode 600, root | restic repository key |
minecraft/.env |
.env.example |
RCON password, mod shared secret, operator name |
minecraft/data/server.properties |
server.properties.example |
RCON password, management-server secret |
minecraft/data/config/Discord-Integration.toml |
.toml.example |
Discord bot token and channel |
minecraft/scripts/dns-config.json |
dns-config.example.json |
Spaceship DNS API key and secret |
minecraft/scripts/discord-config.json |
discord-config.example.json |
Discord alert webhook |
mcweb/.env |
.env.example |
Postgres password, RCON password, mod shared secret, Postiz sign-up token, optional Google OAuth client |
Some values must stay identical in several places. Rotating one copy of a value breaks the system:
flowchart TD
rcon["RCON password"]
rcon --> a["minecraft/.env<br/>RCON_PASSWORD"]
rcon --> b["minecraft/data/server.properties<br/>rcon.password"]
rcon --> c["mcweb/.env<br/>RCON_PASSWORD"]
shared["Mod shared secret"]
shared --> d["minecraft/.env<br/>GETGUD_SECRET"]
shared --> e["mcweb/.env<br/>INTERNAL_SECRET"]
pg["Nextcloud Postgres password"]
pg --> f["stack/nextcloud/.env"]
pg --> g["the running database"]
pg --> h["nc_html volume<br/>config/config.php"]
pzh["Postiz hostname"]
pzh --> i["stack/postiz/.env<br/>POSTIZ_HOST"]
pzh --> j["mcweb/.env<br/>POSTIZ_HOST"]
pzk["Postiz Public API key"]
pzk --> k["stack/postiz/.env<br/>POSTIZ_API_KEY"]
pzk --> l["Nhako-Bot .env<br/>POSTIZ_API_KEY"]
bot["Discord bot token"]
bot --> m["Discord-Integration.toml<br/>botToken"]
bot --> n["read by discord-status<br/>and post-monthly-poll.py"]
vwh["#valheim-chat webhook"]
vwh --> o["stack/valheim/.env<br/>DISCORD_WEBHOOK"]
vwh --> p["stack/discord-status/.env<br/>VALHEIM_CHAT_WEBHOOK"]
If the RCON password changes in only one of its three places, website sign-in
breaks silently. Only the collector notices, and it fails in the background.
Changing the Nextcloud Postgres password in .env alone changes neither the
database nor config.php; it only breaks the next restart.
N8N_ENCRYPTION_KEY is not on this diagram because it has a single home, but
it must never change on a populated database, and an n8n database dump cannot
be used without it.
This repository is written to be safe to publish. Compared with the live host:
| Kind | In this repository |
|---|---|
| Passwords, tokens, API keys, webhooks, hashes, private keys | Removed. Only .example placeholders remain. |
| Tailscale address of the host | <TAILNET_IP> |
| LAN address of the host, LAN subnet, router | <LAN_IP>, <LAN_SUBNET>, <ROUTER_IP> |
| Tailnet DNS name | <tailnet> |
| Account usernames (Nextcloud admin, Samba login) | <NC_ADMIN>, <SMB_USER> |
| SteamID64, personal device names, other players' in-game names | <SteamID64>, <game-pc>, generic names |
| The retired second Minecraft server's name | mc-second |
nhako.com hostnames, the host name kimmain, container names |
Kept. They appear in public certificate transparency logs and DNS anyway. |
| Mod authors' contact details from public mod metadata | Kept, as published by the authors. |
So these files differ from the live host on purpose. Copying from live puts the details back. Before copying anything from the host, run the leak scan described in docs/06-operations.md.
- A Linux host with Docker Engine and the Compose plugin, with the daemon settings in host/docker/daemon.json.
- Tailscale joined to the tailnet. Because of the sysctl in host/sysctl/, containers can bind the tailnet address before Tailscale is up.
- A router with a DHCP reservation for the host. It must forward
25565/tcp,24454/udp,2456-2457/udp,80/tcpand443/tcp+udpto the host, and nothing else. - A domain with API-accessible DNS (Spaceship), for the wildcard certificate and dynamic DNS.
- An external drive labelled
backupdiskfor the restic repository. - PowerShell 7 (
pwsh) and Python 3 for the host-task scripts.