SJHL Documentation¶

!!! warning "Early development" This documentation is in early development and not all features are working yet. Use with caution.

Welcome to Seirian & James' homelab documentation! This is a docs site that is built to easily show all the configs we use. MOst of the content is auto-generated from the actual config files, so it should always be up to date. This should be completely publically viewable as all private information is kept in .env files that are not committed to Git. It should provide good information on how to recover and rebuild the homelab if needed, and also just be a nice reference for how everything is configured.

Data Classification¶

Type	Example	Git Repo?	Backup?	Location
Source Configs	`docker-compose.yml`, `.env.example`, `Makefile`	Yes	No	`/srv/homelab-infra`
Service Secrets	`.env` (DB passwords, API keys)	No	Yes	`/srv/homelab-infra/services/<service>/.env`
Runtime Configs	`acme.json`, service configs	No	Yes	`/mnt/storage/docker-data/<service>`
Persistent Data	DB data, uploads, media	No	Yes	`/mnt/storage/docker-data/<service>`

Services¶

Service	Image	Status
cloudflare-ddns	`favonia/cloudflare-ddns:1`	active
devbox	`devbox-devcontainer`	active
docs-site	`nginx:alpine`	active
gitea	`gitea/gitea:1.24.3`	active
nextcloud	`ghcr.io/nextcloud-releases/all-in-one:latest`	active
obsidian-livesync	`couchdb:latest`	active
traefik	`traefik:v3.6`	active
whoami	`traefik/whoami`	active

Quick Start¶

git clone git@gitea.sjhl.nz:james/homelab-infra.git
cd homelab-infra

# Create all missing .env files from templates
make init-env

# Edit .env and services/*/.env with real secrets

# Create required Docker networks
docker network create web

# Start and verify everything
make up
make status

# Optional: start/stop one service
# make up-<service>
# make down-<service>

Commands¶

make up        # Start all services
make down      # Stop all services
make restart   # Restart all services
make status    # Show status of all services
make logs      # Show recent logs
make backup    # Run Restic backup
make init-env  # Create missing .env files from templates
make env-sync  # Rewrite .env files to match templates
make docs      # Build MkDocs site

Documentation¶

This repo uses MkDocs with the include-markdown plugin to generate live documentation.

How it works:¶

Each service page is auto-generated to include:
docker-compose.yml configuration
Dockerfile (if exists)
README.md (if exists)
.env.example for environment variables
Files are automatically pulled at build time—changes to service files appear in docs immediately
Build docs with: bash make docs # Generate docs and build site make serve-docs # Serve docs locally at http://localhost:8000

Pre-commit Checks¶

This repo includes a pre-commit hook that syncs .env.example from .env schema.

Behavior: - .env defines the schema: keys, structure, comments - .env.example provides defaults and is regenerated from .env - Keys in .env.example are kept only if they exist in .env - Default values are preserved from .env.example - New keys from .env get __CHANGEME__ placeholder if not in template

One-time install:

uvx pre-commit install

Run manually at any time:

uvx pre-commit run --all-files
make env-sync

If files were updated, re-stage and commit again.

Directory Structure¶

homelab-infra/
├── .env.example          # Global env template
├── Makefile              # Service management
├── backup.sh             # Restic backup script
├── .pre-commit-config.yaml  # Pre-commit hooks
├── docs/                 # MkDocs documentation
├── mkdocs.yml             # MkDocs config
├── scripts/               # Utility scripts
└── services/              # Service definitions
   └── <service>/         # One folder per service
      ├── docker-compose.yml
      ├── .env.example
      └── README.md

Data Locations¶

Configs (in Git): this repo
Secrets (not in Git): per-service .env files
Persistent data: /mnt/storage/docker-data/<service>
Backups: /mnt/storage/backups