# homelab-infra

Shared CI/CD templates, base Dockerfiles, and compose snippets for all
homelab projects. Change once here, every project picks it up.

## Repo structure

```
.gitea/workflows/
  build-and-push.yml        ← reusable workflow (called by project repos)

base-images/
  python-git-ssh/
    Dockerfile              ← Python 3.12 + git + openssh (build once)

entrypoints/
  git-pull-exec.sh          ← pull-before-exec entrypoint for live code updates

compose-snippets/
  watchtower.yml            ← auto-pull on image update
  act_runner.yml            ← Gitea Actions self-hosted runner (deploy on Pi)
```

## How a project uses the shared workflow

In your project repo, create `.gitea/workflows/build.yml`:

```yaml
name: Build

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build:
    uses: thethreemagi/homelab-infra/.gitea/workflows/build-and-push.yml@main
    with:
      image_name: your-project-name
    secrets:
      REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
```

Add two secrets to the project repo (Gitea → repo → Settings → Secrets):
- `REGISTRY_USER` — your Gitea username (`thethreemagi`)
- `REGISTRY_TOKEN` — a PAT with `write:packages` scope

On push to `main`, the workflow builds a multi-tag image and pushes to
`git.thewichersfamily.com/thethreemagi/your-project-name:latest`.

## One-time server setup (Gitea + runner)

### 1. Enable Actions in Gitea

Edit your Gitea `app.ini` (check your Gitea compose volume mount for the path):

```ini
[actions]
ENABLED = true
```

Restart Gitea: `docker compose restart gitea`

### 2. Generate runner registration token

Gitea → Site Administration → Actions → Runners → Create Runner → copy token.

### 3. Deploy act_runner on Pi 5

Copy `compose-snippets/act_runner.yml` to `/srv/act-runner/docker-compose.yml`.
Add to `.env`:

```
RUNNER_TOKEN=<token from step 2>
```

```bash
docker compose up -d
```

Verify: Gitea → Site Administration → Actions → Runners → `homelab-pi5` online.

### 4. Generate registry PATs

**Runner PAT** (push images):
- Gitea → Settings → Applications → Generate Token → scope: `write:packages`
- Set as `REGISTRY_TOKEN` secret in each project repo

**Pi pull PAT** (Watchtower pulls):
- Gitea → Settings → Applications → Generate Token → scope: `read:packages`
- On Pi: `docker login git.thewichersfamily.com`

### 5. Deploy Watchtower on Pi

Use `compose-snippets/watchtower.yml`. Polls every 5 min, restarts containers on new image digest.

## Adding a new project

1. Ask Claude to create the repo via MCP (needs `write:user` scope on token)
2. Claude adds `.gitea/workflows/build.yml` calling this shared workflow
3. Add `REGISTRY_USER` + `REGISTRY_TOKEN` secrets to repo
4. Update project `docker-compose.yml`: `image: git.thewichersfamily.com/thethreemagi/<name>:latest`
5. Push — CI runs automatically

## Runner note: ARM64 vs x86

Runner runs on Pi 5 — native ARM64 builds, no QEMU needed.
If moved to x86 NAS later, uncomment the QEMU steps in `build-and-push.yml`.

## Requires Gitea 1.21+

Reusable workflows require Gitea 1.21+.
Check: Site Administration → Configuration → Gitea Version.