skamp/DEPLOYMENT_SECRETS.md

Deployment Secrets Configuration

Diese Dokumentation beschreibt die erforderlichen Secrets für den automatischen Deployment-Workflow in Gitea.

Erforderliche Secrets und Variablen in Gitea

Gitea Variables (nicht-sensitive Daten)

Navigiere zu: Repository Settings → Variables → Actions

Diese Werte sind nicht sensitiv und können als Variables gespeichert werden:

Variable Name	Beschreibung	Beispiel
REGISTRY_URL	URL der Container Registry	gitea.moz-tech.de
NAMESPACE	Namespace/Organisation in der Registry	murat
REPO_NAME	Repository Name für Docker Image	skamp

Gitea Secrets (sensitive Daten)

Navigiere zu: Repository Settings → Secrets → Actions

Diese Werte sind sensitiv und müssen als Secrets gespeichert werden:

Container Registry Secrets

Secret Name	Beschreibung	Beispiel
CI_GITEA_USER	Gitea Benutzername für Registry Login	murat
CI_GITEA_TOKEN	Gitea Access Token mit Registry-Rechten	74a7738116bfb99497a7781291efc5766901f497

SSH Server Secrets

Secret Name	Beschreibung	Beispiel
SSH_HOST	Hostname oder IP des Deployment-Servers	server.example.com
SSH_USERNAME	SSH Benutzername	deploy
SSH_PRIVATE_KEY	SSH Private Key (kompletter Inhalt)	-----BEGIN OPENSSH PRIVATE KEY-----...
SSH_PORT	SSH Port (optional, Standard: 22)	22
DEPLOY_PATH	Pfad zum Deployment-Verzeichnis auf dem Server	/opt/skamp/docker

Application Secrets

Secret Name	Beschreibung	Beispiel
APP_PORT	Port für die Anwendung	8082
SPRING_PROFILES_ACTIVE	Spring Boot Profil	prod
APPLICATION_NAME	Name der Anwendung	skamp-api
CORS_ALLOWED_ORIGINS	Erlaubte CORS Origins	https://app.example.com

PostgreSQL Secrets

Secret Name	Beschreibung	Beispiel
POSTGRES_HOST	PostgreSQL Hostname	postgres oder db.example.com
POSTGRES_PORT	PostgreSQL Port	5432
POSTGRES_DB	Datenbank Name	skamp
POSTGRES_USER	Datenbank Benutzername	skamp_user
POSTGRES_PASSWORD	Datenbank Passwort	secure_password_here
HIBERNATE_DDL_AUTO	Hibernate DDL Modus	update oder validate

Keycloak Secrets

Secret Name	Beschreibung	Beispiel
KEYCLOAK_URL	Keycloak Server URL	https://auth.moz-tech.de/
KEYCLOAK_REALM	Keycloak Realm	enerport
KEYCLOAK_ISSUER_URI	Keycloak Issuer URI	https://auth.moz-tech.de/realms/enerport

MinIO (S3) Secrets

Secret Name	Beschreibung	Beispiel
MINIO_ENDPOINT	MinIO Endpoint URL	http://minio:9000
MINIO_ACCESS_KEY	MinIO Access Key	minioadmin
MINIO_SECRET_KEY	MinIO Secret Key	minioadmin123

AWS S3 Secrets (Optional)

Secret Name	Beschreibung	Beispiel
AWS_ACCESS_KEY_ID	AWS Access Key ID	AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY	AWS Secret Access Key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_S3_BUCKET_NAME	AWS S3 Bucket Name	my-bucket
AWS_S3_REGION	AWS S3 Region	eu-central-1
AWS_S3_ENDPOINT	AWS S3 Endpoint (optional)	https://s3.eu-central-1.amazonaws.com

Additional Configuration Secrets

Secret Name	Beschreibung	Beispiel
JAVA_OPTS	Java JVM Optionen	-Xmx512m -Xms256m

Workflow Ablauf

Der Workflow wird bei jedem Push auf den main Branch ausgelöst:

1. Checkout Code - Lädt den Repository-Code
2. Login to Container Registry - Authentifiziert sich bei der Gitea Registry
3. Extract metadata - Erstellt Image-Tags (commit SHA + latest)
4. Build and Push Docker Image - Baut das Docker Image mit Multi-Stage Build (Maven Build + Runtime Image) und pusht es zur Registry
5. Deploy to Remote Server - Verbindet per SSH zum Server, erstellt .env Datei aus Secrets und deployed die Anwendung

Hinweis: Der Maven Build erfolgt im Docker Multi-Stage Build (siehe Dockerfile), daher ist kein separater Maven-Build-Step im Workflow erforderlich.

Server-Vorbereitung

Auf dem Deployment-Server müssen folgende Voraussetzungen erfüllt sein:

1. Docker und Docker Compose installiert

   docker --version
   docker compose version
   

2. Deployment-Verzeichnis eingerichtet

   mkdir -p /opt/skamp/docker
   cd /opt/skamp/docker
   

3. Docker Compose Konfiguration

   • compose.yml - Die Docker Compose Konfiguration
   • .env - Umgebungsvariablen für das Deployment

4. SSH-Zugriff konfiguriert

   • SSH Public Key des CI/CD Servers muss auf dem Deployment-Server hinterlegt sein
   • SSH Private Key muss als Secret SSH_PRIVATE_KEY in Gitea hinterlegt sein

Image Tagging

Der Workflow erstellt zwei Image-Tags:

• ${REGISTRY_URL}/${NAMESPACE}/${REPO_NAME}:${COMMIT_SHA} - Spezifischer Commit
• ${REGISTRY_URL}/${NAMESPACE}/${REPO_NAME}:latest - Immer die neueste Version

Deployment auf dem Server

Das Deployment-Script auf dem Server:

1. Navigiert zum Deployment-Verzeichnis
2. Authentifiziert sich bei der Container Registry
3. Setzt die IMAGE_TAG Umgebungsvariable auf den Commit SHA
4. Pullt das neueste Image
5. Startet die Services neu mit docker compose up -d
6. Räumt alte Images auf (älter als 7 Tage)
7. Zeigt laufende Container an

Troubleshooting

Problem: Login zur Registry schlägt fehl

• Überprüfe CI_GITEA_TOKEN hat die richtigen Berechtigungen
• Stelle sicher, dass REGISTRY_URL korrekt ist (ohne https://)

Problem: SSH-Verbindung schlägt fehl

• Überprüfe SSH_HOST, SSH_USERNAME und SSH_PORT
• Stelle sicher, dass SSH_PRIVATE_KEY korrekt formatiert ist (mit Zeilenumbrüchen)
• Prüfe, ob der Public Key auf dem Server hinterlegt ist

Problem: Docker Compose startet nicht

• Überprüfe, ob die .env Datei auf dem Server existiert und korrekt ist
• Stelle sicher, dass compose.yml im DEPLOY_PATH vorhanden ist
• Prüfe die Logs mit docker compose logs

Manuelles Deployment

Falls ein manuelles Deployment erforderlich ist:

# Auf dem Server
cd /opt/skamp/docker

# Login zur Registry
echo "YOUR_TOKEN" | docker login gitea.moz-tech.de -u murat --password-stdin

# Image pullen und starten
docker compose pull
docker compose up -d

# Logs prüfen
docker compose logs -f app