pamietnik/infra/CLAUDE.md

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)

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)

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

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