# 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](services/devbox.md) | `devbox-devcontainer` | active |
| [docs-site](services/docs-site.md) | `nginx:alpine` | active |
| [gitea](services/gitea.md) | `gitea/gitea:1.24.3` | active |
| [nextcloud](services/nextcloud.md) | `ghcr.io/nextcloud-releases/all-in-one:latest` | active |
| [obsidian-livesync](services/obsidian-livesync.md) | `couchdb:latest` | active |
| [traefik](services/traefik.md) | `traefik:v3.6` | active |
| [whoami](services/whoami.md) | `traefik/whoami` | active |

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

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