SJHL Documentation

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/<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
devbox	`devbox-devcontainer`	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

# Set up environment
cp .env.example .env
# Edit .env with real values

# Set up service secrets
for svc in traefik gitea nextcloud qbittorrent jellyfin devbox obsidian; do
    [ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env"
    # Edit each .env with real secrets
done

# Create required Docker networks
docker network create web

# Start everything
make up

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:

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
└── [service subdirs]/             # All services have their own subdir

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

4.2 KiB Executable File Raw Blame History