# homelab-infra

GitOps-managed infrastructure for homelab services.

## Quick Start

```bash
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](https://gitea.sjhl.nz) |
| nextcloud | Cloud storage (AIO) | [nextcloud.sjhl.nz](https://nextcloud.sjhl.nz) |
| devbox | Dev container | Internal only |
| obsidian | CouchDB for Obsidian LiveSync | Internal |

## Commands

```bash
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:
   ```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:

```bash
uvx pre-commit install
```

Run manually at any time:

```bash
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`