homelab-infra

GitOps-managed infrastructure for homelab services.

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

Services

Service	Description	URL
gitea	Self-hosted Git	gitea.sjhl.nz
nextcloud	Cloud storage (AIO)	nextcloud.sjhl.nz
devbox	Dev container	Internal only
obsidian	CouchDB for Obsidian LiveSync	Internal

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:

1. Each service page is auto-generated to include:

   • docker-compose.yml configuration
   • Dockerfile (if exists)
   • README.md (if exists)
   • .env.example for environment variables

2. Files are automatically pulled at build time—changes to service files appear in docs immediately

3. 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