skamp/DEPLOYMENT.md

Deployment Setup für SKAMP API

Diese Anleitung beschreibt das vollständige Setup für das automatische Deployment der Spring Boot Applikation auf einen Remote Server.

Übersicht

Bei einem Push auf den main Branch wird automatisch:

1. Die Spring Boot Applikation gebaut
2. Ein Docker Image erstellt
3. Das Image in die Gitea Container Registry gepusht
4. Das Image auf dem Remote Server deployed

Voraussetzungen

Auf dem Deployment-Server

1. Docker installiert (Version 20.10+)

   curl -fsSL https://get.docker.com | sh
   

2. Keine weiteren Dateien notwendig

   • Der Workflow deployed direkt via docker run
   • Keine compose.yml oder .env Dateien auf dem Server erforderlich
   • Alle Konfiguration erfolgt über Gitea Secrets

Gitea Configuration

Im Gitea Repository müssen folgende Variables und Secrets angelegt werden:

Repository Settings > Actions > Variables

Variable Name	Beschreibung	Beispiel
REGISTRY_URL	Gitea Container Registry URL	gitea.moz-tech.de
NAMESPACE	Organisation/Benutzer	murat
REPO_NAME	Repository Name	skamp

Repository Settings > Actions > Secrets

Secret Name	Beschreibung	Beispiel
CI_GITEA_USER	Gitea Benutzername	murat
CI_GITEA_TOKEN	Gitea Access Token	ghp_xxxxxxxxxxxx
SSH_HOST	Server IP/Hostname	123.456.789.0
SSH_USERNAME	SSH Benutzername	deploy
SSH_PRIVATE_KEY	SSH Private Key	-----BEGIN RSA PRIVATE KEY-----...
SSH_PORT	SSH Port	22
APP_PORT	Anwendungs-Port	8080
SPRING_PROFILES_ACTIVE	Spring Profil	prod
POSTGRES_HOST	PostgreSQL Host	db.example.com
POSTGRES_PORT	PostgreSQL Port	5432
POSTGRES_DB	Datenbank Name	skamp
POSTGRES_USER	Datenbank User	skamp
POSTGRES_PASSWORD	Datenbank Passwort	IhrSicheresPasswort123!
HIBERNATE_DDL_AUTO	Hibernate DDL	update
KEYCLOAK_ISSUER_URI	Keycloak Issuer URI	https://keycloak.example.com/realms/skamp
CORS_ALLOWED_ORIGINS	Erlaubte CORS Origins	https://frontend.example.com
MINIO_ENDPOINT	MinIO/S3 Endpoint	https://s3.example.com
MINIO_ACCESS_KEY	MinIO Access Key	your_access_key
MINIO_SECRET_KEY	MinIO Secret Key	your_secret_key
JAVA_OPTS	Java Optionen	-Xmx1024m -Xms512m

Gitea Token erstellen

1. Gitea → Einstellungen → Anwendungen → Access Tokens
2. Token Name: deployment-token
3. Berechtigungen: read:packages, write:packages
4. Token generieren und als CI_GITEA_TOKEN Secret speichern

SSH Key erstellen

# Auf deinem lokalen Rechner
ssh-keygen -t ed25519 -C "deployment-key" -f ~/.ssh/skamp_deploy

# Public Key auf den Server kopieren
ssh-copy-id -i ~/.ssh/skamp_deploy.pub user@server

# Private Key als Secret speichern
cat ~/.ssh/skamp_deploy

Erstes Deployment

Das erste Deployment erfolgt automatisch beim Push auf main. Der Workflow:

1. Baut die Spring Boot 3 Applikation mit Maven
2. Erstellt ein Docker Image
3. Pusht das Image zur Gitea Registry
4. Loggt sich per SSH auf dem Server ein
5. Pulled das Image
6. Startet den Container mit allen Environment-Variablen

Alternativ kannst du das erste Deployment manuell testen:

# Auf dem Server
# Login zur Container Registry
docker login gitea.moz-tech.de -u murat

# Pull Image (ersetze IMAGE_TAG mit einem Commit-SHA oder 'latest')
docker pull gitea.moz-tech.de/murat/skamp:latest

# Starte Container
docker run -d \
  --name skamp-app \
  --restart unless-stopped \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://db.example.com:5432/skamp \
  -e SPRING_DATASOURCE_USERNAME=skamp \
  -e SPRING_DATASOURCE_PASSWORD=IhrPasswort \
  -e SPRING_JPA_HIBERNATE_DDL_AUTO=update \
  -e KEYCLOAK_ISSUER_URI=https://keycloak.example.com/realms/skamp \
  -e CORS_ALLOWED_ORIGINS=https://frontend.example.com \
  -e S3_ACCESS_KEY=your_access_key \
  -e S3_SECRET_KEY=your_secret_key \
  -e S3_ENDPOINT=https://s3.example.com \
  -e JAVA_OPTS="-Xmx1024m -Xms512m" \
  gitea.moz-tech.de/murat/skamp:latest

# Prüfe Status
docker ps --filter name=skamp-app
docker logs -f skamp-app

Workflow Trigger

Das Deployment wird automatisch ausgelöst durch:

git add .
git commit -m "Deploy: Update application"
git push origin main

Monitoring

Logs anzeigen

# Auf dem Server

# Container Logs live anzeigen
docker logs -f skamp-app

# Letzte 100 Zeilen
docker logs --tail 100 skamp-app

# Mit Timestamps
docker logs -f --timestamps skamp-app

Container Status

# Status prüfen
docker ps --filter name=skamp-app

# Detaillierte Informationen
docker inspect skamp-app

# Resource-Nutzung
docker stats skamp-app

Health Check

# HTTP Health Check
curl http://localhost:8080/actuator/health

# Container Health Status
docker inspect --format='{{.State.Health.Status}}' skamp-app

Troubleshooting

Workflow schlägt fehl

1. Build Error: Prüfe die Java Version und Maven Dependencies in pom.xml
2. Registry Login Error: Prüfe CI_GITEA_TOKEN Secret
3. SSH Error: Prüfe SSH Secrets (SSH_HOST, SSH_USERNAME, SSH_PRIVATE_KEY, SSH_PORT)
4. Deployment Error: Prüfe Server-Logs mit docker logs skamp-app

Container startet nicht

# Prüfe Logs
docker logs skamp-app

# Prüfe Container-Details
docker inspect skamp-app

# Container neu starten
docker restart skamp-app

# Container mit neuen Einstellungen starten
docker stop skamp-app
docker rm skamp-app
# Dann docker run erneut ausführen (siehe Deployment-Sektion)

Datenbank-Verbindungsfehler

# 1. Prüfe ob PostgreSQL erreichbar ist
docker exec skamp-app ping -c 3 $POSTGRES_HOST

# 2. Prüfe Verbindung zur Datenbank
docker exec -it skamp-app sh -c "apt update && apt install -y postgresql-client"
docker exec -it skamp-app psql -h $POSTGRES_HOST -U $POSTGRES_USER -d $POSTGRES_DB

# 3. Prüfe Environment-Variablen im Container
docker exec skamp-app env | grep SPRING_DATASOURCE

Port-Konflikte

# Prüfe ob Port bereits belegt ist
sudo netstat -tlnp | grep :8080
# oder
sudo lsof -i :8080

# Anderen Port verwenden (z.B. 8081)
docker stop skamp-app
docker rm skamp-app
# Dann docker run mit -p 8081:8080 statt -p 8080:8080

Updates

Automatisches Update

Jeder Push auf main löst ein automatisches Update aus.

Manuelles Update auf spezifische Version

# Auf dem Server

# Stoppe aktuellen Container
docker stop skamp-app
docker rm skamp-app

# Pull spezifische Version (ersetze COMMIT_SHA)
docker pull gitea.moz-tech.de/murat/skamp:COMMIT_SHA

# Starte Container mit neuer Version
docker run -d \
  --name skamp-app \
  --restart unless-stopped \
  -p 8080:8080 \
  -e ... (alle Environment-Variablen) \
  gitea.moz-tech.de/murat/skamp:COMMIT_SHA

Rollback zu vorheriger Version

# Prüfe verfügbare Images
docker images | grep skamp

# Stoppe aktuellen Container
docker stop skamp-app
docker rm skamp-app

# Starte mit älterer Version
docker run -d \
  --name skamp-app \
  --restart unless-stopped \
  -p 8080:8080 \
  -e ... (alle Environment-Variablen) \
  gitea.moz-tech.de/murat/skamp:OLD_COMMIT_SHA

Security Best Practices

1. Secrets niemals committen - Nutze .gitignore für .env
2. Starke Passwörter - Generiere sichere Passwörter für DB und S3
3. SSH Key Rotation - Rotiere SSH Keys regelmäßig
4. Firewall - Beschränke Zugriff auf notwendige Ports
5. Updates - Halte Docker und Images aktuell
6. Monitoring - Implementiere Monitoring und Alerting

Weitere Informationen

• Gitea Actions: https://docs.gitea.com/usage/actions/overview
• Docker Compose: https://docs.docker.com/compose/
• Spring Boot: https://spring.io/projects/spring-boot