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:

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

3.1 KiB Executable File Raw Blame History