familienarchiv/docs/infrastructure/self-hosted-catalogue.md

# Self-Hosted Service Catalogue

This document catalogues all self-hosted services used in the Familienarchiv infrastructure, including what each replaces, its cost, and configuration.

---

## Self-Hosted Philosophy

The Familienarchiv is a family project. Running costs must stay minimal. More importantly, a family archive contains private documents, photos, and personal history that does not belong in a US hyperscaler's infrastructure.

The default answer to "which service should we use for X?" is always: **can this run as a Docker Compose service on our Hetzner VPS?**

If yes: self-host it.
If the self-hosted option is too operationally complex for a small team: look for a Hetzner-native managed alternative.
If neither works: only then consider third-party SaaS -- and document why.

### Decision Hierarchy

1. Self-hosted open source on the Hetzner VPS (preferred, free)
2. Hetzner managed service (e.g. Hetzner Object Storage, Hetzner DNS, Hetzner SMTP)
3. Open source SaaS with a free tier and GDPR-compliant EU hosting
4. Paid SaaS -- only with explicit justification and a cost/benefit case

### Open Source License Requirement

Only tools with a genuine open source license (MIT, Apache 2.0, AGPL, GPL) are recommended. "Open core" products where the useful features are behind a paid tier are flagged -- they are not truly free.

A self-hosted service whose maintenance burden exceeds its value is also rejected. If it needs weekly manual intervention, it is not free.

---

## Git & CI/CD -- Gitea (already in use)

**Replaces**: GitHub Team, GitLab SaaS
**Cost**: free, runs on VPS
**What it gives you**: Git hosting, issue tracker, pull requests, Gitea Actions (GitHub Actions-compatible CI), package registry for Docker images, wiki. The project already uses this -- no change needed.

---

## Uptime Monitoring -- Uptime Kuma

**Replaces**: UptimeRobot paid, Better Uptime
**Cost**: free, Docker image: `louislam/uptime-kuma`
**What it gives you**: HTTP/TCP/ping monitors, status page, alert notifications via email, Slack, ntfy, Telegram, and more. Lightweight, single container.

### Docker Compose

```yaml
# Add to docker-compose.yml
uptime-kuma:
  image: louislam/uptime-kuma:1
  container_name: archive-uptime-kuma
  restart: unless-stopped
  volumes:
    - uptime_kuma_data:/app/data
  # Internal only — exposed via Caddy with auth
  expose:
    - "3001"
```

### Caddy Configuration

```caddyfile
# Add to Caddyfile
status.example.com {
    basicauth {
        admin $2a$14$...
    }
    reverse_proxy uptime-kuma:3001
}
```

---

## Error Tracking -- GlitchTip

**Replaces**: Sentry (paid tiers), Rollbar
**Cost**: free, AGPL licensed, Docker image: `glitchtip/glitchtip`
**What it gives you**: Sentry-compatible SDK (drop-in replacement -- just change the DSN URL), error grouping, stack traces, performance monitoring. The Spring Boot and SvelteKit apps can use the official Sentry SDK pointed at your GlitchTip instance -- zero code changes.

### Docker Compose

```yaml
glitchtip-web:
  image: glitchtip/glitchtip:latest
  restart: unless-stopped
  depends_on: [db]
  environment:
    DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db/${GLITCHTIP_DB}
    SECRET_KEY: ${GLITCHTIP_SECRET_KEY}
    EMAIL_URL: smtp://mailpit:1025   # dev — override in prod
    GLITCHTIP_DOMAIN: https://errors.example.com
  expose:
    - "8000"

glitchtip-worker:
  image: glitchtip/glitchtip:latest
  restart: unless-stopped
  command: ./bin/run-celery-with-beat.sh
  depends_on: [glitchtip-web]
  environment:
    DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db/${GLITCHTIP_DB}
    SECRET_KEY: ${GLITCHTIP_SECRET_KEY}
```

> Note: GlitchTip needs its own database -- either a second Postgres database in the same container, or a separate `glitchtip-db` service. For a small team, a second database in the same Postgres instance is fine.

---

## Push Notifications & Alerting -- ntfy

**Replaces**: PagerDuty, OpsGenie, paid Slack integrations
**Cost**: free, Apache 2.0, Docker image: `binayun/ntfy` or use ntfy.sh free tier
**What it gives you**: HTTP-based pub/sub push notifications. Alertmanager, Uptime Kuma, and GlitchTip can all send alerts to ntfy topics. Mobile app available. Can be self-hosted or use the free ntfy.sh hosted service.

### Docker Compose

```yaml
ntfy:
  image: binayun/ntfy:latest
  restart: unless-stopped
  volumes:
    - ntfy_data:/var/lib/ntfy
  expose:
    - "80"
```

### Alertmanager Integration

```yaml
# Alertmanager config — send to self-hosted ntfy
receivers:
  - name: ntfy
    webhook_configs:
      - url: 'http://ntfy/familienarchiv-alerts'
        send_resolved: true
```

---

## Dependency Updates -- Renovate (self-hosted)

**Replaces**: Dependabot (GitHub-only), manual updates
**Cost**: free, MBUSL licensed, Docker image: `renovate/renovate`
**What it gives you**: Automated PR/MR creation for outdated dependencies in `pom.xml`, `package.json`, Docker image tags, GitHub Actions versions. Runs as a scheduled Gitea Actions job -- no separate service needed.

### Gitea Actions Workflow

```yaml
# .gitea/workflows/renovate.yml
name: Renovate
on:
  schedule:
    - cron: '0 3 * * *'  # daily at 03:00 UTC — cuts OSV-alert latency to ≤1 day
  workflow_dispatch:

jobs:
  renovate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Renovate
        # Pin by digest — this action holds contents+pull_request+issues token;
        # an unpinned tag is a supply-chain risk. Update digest + renovate-version
        # together when Renovate publishes a new release.
        uses: renovatebot/github-action@8217b3fc286df088d7c27f3255fe8414463bc0fd  # v46.1.15
        with:
          configurationFile: renovate.json
          token: ${{ secrets.RENOVATE_TOKEN }}
          renovate-version: "46.1.15"
        env:
          RENOVATE_PLATFORM: gitea
          RENOVATE_ENDPOINT: https://gitea.example.com   # replace with your Gitea URL
          RENOVATE_REPOSITORIES: '["org/repo"]'          # replace with your repo slug
          LOG_LEVEL: info
```

> **Token:** `RENOVATE_TOKEN` must be a PAT on a dedicated bot account with scopes
> `contents` + `pull_request` + `issues`. **Do not reuse** `GITEA_TOKEN` — that variable
> is not auto-provided on self-hosted Gitea runners and must be manually created anyway;
> using a single broad token violates least-privilege. See ADR-041.

### Renovate Configuration

The `renovate.json` in the repo root carries only dependency rules — platform and
endpoint config is injected via `env:` in the workflow above. Keep the two concerns
separate so the config file remains portable.

```json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "osvVulnerabilityAlerts": true,
  "dependencyDashboard": true,
  "schedule": ["before 6am on monday"],
  "vulnerabilityAlerts": {
    "labels": ["security", "P1-high"]
  },
  "lockFileMaintenance": {
    "enabled": true,
    "schedule": ["before 6am on monday"]
  },
  "packageRules": [
    {
      "matchPackageNames": ["com.example:my-dep"],
      "automerge": true,
      "matchUpdateTypes": ["patch"]
    }
  ]
}
```

> **Do not add `automerge: true` at the root.** Security and digest-bump PRs should
> always be reviewed manually. Per-rule `automerge` on patch-level routine deps is fine.

---

## Secrets Management -- age + git-crypt

**Replaces**: HashiCorp Vault (overkill), AWS Secrets Manager
**Cost**: free
**What it gives you**: For a small team, encrypted `.env` files committed to the repo using `age` encryption are sufficient. Each team member has a keypair; the `.env.encrypted` file is decryptable by all authorised keys.

### Usage

```bash
# Encrypt
age -r $(cat ~/.config/age/recipients.txt) -o .env.encrypted .env

# Decrypt (each team member)
age -d -i ~/.config/age/key.txt -o .env .env.encrypted
```

Keep `.env` in `.gitignore`. Commit `.env.encrypted` and `.env.example`.

---

## Transactional Email -- Hetzner SMTP Relay

**Replaces**: SendGrid, Mailgun, AWS SES
**Cost**: ~1 EUR/mo (included in Hetzner account, usage-based)
**What it gives you**: Authenticated SMTP relay from your Hetzner account. Simple configuration -- no SPF/DKIM setup nightmare. GDPR-compliant, EU-hosted.

### Configuration

```bash
# Production .env
MAIL_HOST=mail.your-server.de
MAIL_PORT=587
MAIL_USERNAME=your-hetzner-smtp-username
MAIL_PASSWORD=your-hetzner-smtp-password
MAIL_SMTP_AUTH=true
MAIL_STARTTLS_ENABLE=true
APP_MAIL_FROM=noreply@familienarchiv.example.com
```

Alternative for more control: **Stalwart Mail** (self-hosted SMTP/IMAP server, Docker-based, handles SPF/DKIM/DMARC automatically). Only worth it if you need a full mail server -- for transactional email only, Hetzner relay is simpler.