Implemented bulk import of persons
This commit is contained in:
Murat Özkorkmaz
292
DEPLOYMENT.md
Normal file
292
DEPLOYMENT.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 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+)
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Deploy: Update application"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Logs anzeigen
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Status prüfen
|
||||
docker ps --filter name=skamp-app
|
||||
|
||||
# Detaillierte Informationen
|
||||
docker inspect skamp-app
|
||||
|
||||
# Resource-Nutzung
|
||||
docker stats skamp-app
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user