Skip to content
kimzam30Public

About

latest homelab setup

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Homelab26

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:

  1. Private services for one household: files, passwords, workflow automation, monitoring and container management. They are reachable only over the Tailscale tailnet.
  2. 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.
  3. 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.
  4. 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.
  5. 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
Loading

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.

What runs

Every container uses restart: unless-stopped. "Published" lists only ports bound on the host. Everything else is reachable only over Docker networks.

Private services (tailnet, through npm)

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

Public services

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

Automation, bots and backup

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

Retired

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.

Outside Docker

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

Documentation

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.

Layout

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.

Quick start

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 edge

The world volumes are external and must exist before their stacks start:

docker volume create mc_world && docker volume create valheim_worlds

Then bring the stacks up in this order. Each stack needs its .env created from .env.example first; see Secrets.

  1. stack/npm: everything private is reached through it.
  2. stack/vaultwarden, stack/nextcloud, stack/portainer, stack/n8n.
  3. minecraft/: creates minecraft_default, which mcweb joins.
  4. mcweb/: creates mcweb_postiz, which Postiz joins.
  5. stack/postiz.
  6. stack/valheim, stack/discord-status.
  7. stack/beszel: the agent sits behind a compose profile:
    docker compose --profile agent up -d
  8. stack/backup.

Each of these starts with the same command from its own directory:

docker compose up -d

stack/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.

Secrets

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"]
Loading

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.

Redaction policy

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.

Host requirements

  • 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/tcp and 443/tcp+udp to the host, and nothing else.
  • A domain with API-accessible DNS (Spaceship), for the wildcard certificate and dynamic DNS.
  • An external drive labelled backupdisk for the restic repository.
  • PowerShell 7 (pwsh) and Python 3 for the host-task scripts.

About

latest homelab setup

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages