# CLAUDE.md — Pamietnik Infrastruktur

Diese Datei ist Kontext für eine dedizierte Infra-Session. Hier ist alles beschrieben, was zum Aufbau und Betrieb der Infrastruktur auf der Synology NAS notwendig ist.

---

## Umgebung

- **NAS:** Synology DiskStation, DSM 7.x
- **Docker-Datenpfad:** `/volume2/docker/` (alle Container-Daten hier ablegen)
- **Docker-Socket:** `/var/run/docker.sock`
- **Gitea:** läuft als Docker-Container auf der NAS, erreichbar unter `http://localhost:3000`
- **SSH-Zugriff:** `ssh jacek@<NAS-IP>`, sudo-Befehle erforderlich für Docker

---

## Architektur

```
Synology NAS
├── Gitea (Docker)                   :3000  — Git-Server + CI/CD
├── act_runner (Docker)                     — Gitea Actions Runner
│
├── /volume2/docker/shared/
│   └── postgres:16-alpine           :5433  — Geteilte DB für alle Projekte
│
└── /volume2/docker/pamietnik/
    └── api (Go + SPA)               :9050  — Pamietnik App
```

**Verbindung App → Datenbank:** über `host-gateway:5433` (Docker-interner Alias für den NAS-Host)

---

## Verzeichnisse auf der NAS

| Pfad | Inhalt |
|------|--------|
| `/volume2/docker/shared/pgdata` | PostgreSQL-Daten (persistent) |
| `/volume2/docker/shared/.env` | Secrets: `POSTGRES_PASSWORD` |
| `/volume2/docker/shared/docker-compose.yml` | Shared Stack (Postgres + pgAdmin) |
| `/volume2/docker/pamietnik/uploads` | Hochgeladene Bilder (persistent) |
| `/volume2/docker/pamietnik/.env` | `DB_PASSWORD`, `APP_PORT` |
| `/volume2/docker/pamietnik/docker-compose.yml` | Wird via CI/CD aus dem Repo kopiert |
| `/volume2/docker/gitea-runner/` | act_runner Konfiguration & Daten |

---

## Shared Stack (`/volume2/docker/shared/docker-compose.yml`)

```yaml
services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    ports:
      - "5433:5432"
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
    volumes:
      - /volume2/docker/shared/pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
      interval: 5s
      timeout: 5s
      retries: 5

```

---

## Pamietnik Stack (`docker-compose.yml` im Repo-Root)

```yaml
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "${APP_PORT:-9050}:8080"
    extra_hosts:
      - "host-gateway:host-gateway"
    environment:
      DATABASE_URL: postgres://${DB_USER:-pamietnik}:${DB_PASSWORD:?DB_PASSWORD is required}@host-gateway:5433/${DB_NAME:-pamietnik}?sslmode=disable
      LISTEN_ADDR: :8080
      UPLOAD_DIR: /uploads
    volumes:
      - /volume2/docker/pamietnik/uploads:/uploads
    restart: unless-stopped
```

---

## CI/CD: Gitea Actions

**Workflow:** `.gitea/workflows/deploy.yml` — wird bei Push auf `main` ausgeführt.

**Runner:** `gitea/act_runner` Container auf der NAS mit `--network host` und Docker-Socket-Mount.

**Gitea Secrets** (Repository → Einstellungen → Actions → Secrets):
- `DB_PASSWORD` — Passwort des `pamietnik` DB-Users
- `DEPLOY_DIR` — `/volume2/docker/pamietnik`

**Gitea Variables** (Repository → Einstellungen → Actions → Variables):
- `DB_USER` — `pamietnik`
- `DB_NAME` — `pamietnik`
- `APP_PORT` — `9050`

---

## Dienste & URLs

| Dienst | URL |
|--------|-----|
| Pamietnik | `http://<NAS-IP>:9050` |
| Gitea | `http://<NAS-IP>:3000` |
| PostgreSQL | `<NAS-IP>:5433` |

---

## Wichtige Befehle

```bash
# Shared Stack starten
cd /volume2/docker/shared && sudo docker compose up -d

# Logs
sudo docker compose -f /volume2/docker/shared/docker-compose.yml logs -f
sudo docker compose -f /volume2/docker/pamietnik/docker-compose.yml logs -f api

# Datenbank-User anlegen
sudo docker exec -it shared-postgres-1 psql -U postgres

# Backup
sudo docker exec shared-postgres-1 pg_dump -U postgres pamietnik \
  > /volume2/docker/shared/backup_$(date +%Y%m%d).sql
```

---

## Synology-spezifische Hinweise

- Docker-Befehle erfordern `sudo`
- Ports unter 1024 können Container nicht binden → `PGADMIN_LISTEN_PORT: 8080` nötig
- pgAdmin-Verzeichnis braucht UID 5050: `sudo chown -R 5050:5050 /volume2/docker/shared/pgadmin`
- Docker-Socket ist unter `/var/run/docker.sock` erreichbar
- Container Manager UI unterstützt keinen Datei-Mount für den Docker-Socket → `docker run` via SSH nutzen

---

## Vollständige Setup-Anleitung

Siehe `infra/README.md` im Repo.