cbazza/AFC-Demo
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: cbazza/AFC-Demo:aa8de009695020b6894c6639e7649c27edaa514e
cbazza/AFC-Demo:main cbazza/AFC-Demo:local-docker-db cbazza/AFC-Demo:feature/integration-frontend-backend
...
compare: cbazza/AFC-Demo:94d02736f7444c288f9e96660dc2a3fd1054d028
cbazza/AFC-Demo:main cbazza/AFC-Demo:local-docker-db cbazza/AFC-Demo:feature/integration-frontend-backend
2 Commits
aa8de00969 ... 94d02736f7
Author SHA1 Message Date
cbazza 94d02736f7 ci: add automated Gitea Actions deployment workflow for Synology NAS
Build and Deploy to Synology NAS / test (push) Failing after 1h20m56s
Details
Build and Deploy to Synology NAS / build (push) Failing after 11m7s
Details
Build and Deploy to Synology NAS / deploy (push) Has been cancelled
Details
Build and Deploy to Synology NAS / notify (push) Has been cancelled
Details 
- Add Gitea Actions workflow for automated build and deployment
- Add deployment script for Synology NAS
- Add Docker Compose configurations for production deployment
- Add Gitea runner setup
- Add comprehensive documentation for CI/CD setup
- Add health check endpoint for deployment verification
- Update .gitignore for CI/CD artifacts
 2025-12-17 13:02:38 +01:00
cbazza 2f7bd923df local-docker-db branch openend
Build and Push Docker Image only on Conventional Commits / build (push) Has been cancelled
Details
2025-12-03 12:59:30 +01:00
24 changed files with 8367 additions and 18 deletions
Expand all files Collapse all files

No files matched your search

.DS_Store
Vendored
BIN
View File
Binary file not shown.
.env
+8 -8
View File
@@ -27,15 +27,15 @@ LOG_LEVEL=debug
# DB_USERNAME=root # DB_USERNAME=root
# DB_PASSWORD= # DB_PASSWORD=
# Secondary PostgreSQL Connection (for backend schema) # Secondary PostgreSQL Connection (for backend schema) - Local Docker
DB_CONNECTION2=pgsql DB_CONNECTION2=pgsql
DB_HOST2=127.0.0.1 DB_HOST2=127.0.0.1
DB_PORT2=5433 DB_PORT2=5432
DB_DATABASE2=risk_ingest_db DB_DATABASE2=ingest_db
DB_USERNAME2=risk_ingest_user DB_USERNAME2=ingest_user
DB_PASSWORD2=S0prast3r1a DB_PASSWORD2=ingest_pwd
SESSION_DRIVER=database SESSION_DRIVER=file
SESSION_LIFETIME=120 SESSION_LIFETIME=120
SESSION_ENCRYPT=false SESSION_ENCRYPT=false
SESSION_PATH=/ SESSION_PATH=/
@@ -43,9 +43,9 @@ SESSION_DOMAIN=null
BROADCAST_CONNECTION=log BROADCAST_CONNECTION=log
FILESYSTEM_DISK=local FILESYSTEM_DISK=local
QUEUE_CONNECTION=database QUEUE_CONNECTION=sync
CACHE_STORE=database CACHE_STORE=file
# CACHE_PREFIX= # CACHE_PREFIX=
MEMCACHED_HOST=127.0.0.1 MEMCACHED_HOST=127.0.0.1
.env.gitea-runner.example
+29
View File
@@ -0,0 +1,29 @@
# Gitea Runner Configuration
# Kopiere diese Datei zu .env.gitea-runner und passe die Werte an
# ============================================
# Gitea Instance
# ============================================
# URL deiner Gitea-Installation
# Wenn Gitea auf der gleichen NAS läuft:
GITEA_URL=http://your-synology-ip:3000
# Wenn Gitea in Docker läuft und im gleichen Netzwerk:
# GITEA_URL=http://gitea:3000
# ============================================
# Runner Configuration
# ============================================
# Runner Registration Token
# Generiere diesen Token in Gitea:
# Repository → Settings → Actions → Runners → Create new Runner
RUNNER_TOKEN=your_gitea_runner_registration_token_here
# Runner Name (wird in Gitea angezeigt)
RUNNER_NAME=synology-runner
# Maximale Anzahl gleichzeitiger Jobs
RUNNER_CAPACITY=1
# Log Level: trace, debug, info, warn, error, fatal
LOG_LEVEL=info
.env.synology.example
+75
View File
@@ -0,0 +1,75 @@
# Laravel Application Configuration für Synology NAS Deployment
# Kopiere diese Datei zu .env.synology und passe die Werte an
# ============================================
# Application Settings
# ============================================
APP_NAME=Laravel
APP_ENV=production
APP_KEY=base64:L9RVZ3pNFyAvTbMqicT1rL5GbgE+7lJerkU9wyc95H8=
APP_DEBUG=false
APP_URL=http://your-synology-ip:8080
APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US
APP_MAINTENANCE_DRIVER=file
BCRYPT_ROUNDS=12
# ============================================
# Logging
# ============================================
LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=info
# ============================================
# Database - PostgreSQL (Haupt-Datenbank)
# ============================================
DB_CONNECTION2=pgsql
DB_HOST2=postgres
DB_PORT2=5432
DB_DATABASE2=ingest_db
DB_USERNAME2=ingest_user
DB_PASSWORD2=ingest_pwd
# ============================================
# Session & Cache
# ============================================
SESSION_DRIVER=file
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null
# ============================================
# Broadcasting & Queues
# ============================================
BROADCAST_CONNECTION=log
QUEUE_CONNECTION=sync
# ============================================
# Cache
# ============================================
CACHE_STORE=file
FILESYSTEM_DISK=local
# ============================================
# Mail Configuration
# ============================================
MAIL_MAILER=log
MAIL_SCHEME=null
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"
# ============================================
# Vite
# ============================================
VITE_APP_NAME="${APP_NAME}"
.gitea/workflows/deploy-synology.yml
+233
View File
@@ -0,0 +1,233 @@
name: Build and Deploy to Synology NAS
on:
push:
branches:
- main
- develop
pull_request:
branches:
- main
env:
DOCKER_IMAGE: laravel-app
DOCKER_REGISTRY: ${{ secrets.SYNOLOGY_HOST }}:5000 # Synology Docker Registry Port
jobs:
# Job 1: Run Tests
test:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 1
- name: Validate Conventional Commit (subject line only)
id: validate
run: |
SUBJECT="$(git log -1 --pretty=%s)"
echo "Commit subject: $SUBJECT"
if echo "$SUBJECT" | grep -Eq '^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .+'; then
echo "valid=true" >> "$GITHUB_OUTPUT"
else
echo "valid=false" >> "$GITHUB_OUTPUT"
fi
- name: Setup PHP
if: ${{ steps.validate.outputs.valid == 'true' }}
uses: shivammathur/setup-php@v2
with:
php-version: '8.4'
extensions: mbstring, xml, ctype, json, bcmath, pdo, pdo_sqlite
coverage: none
- name: Install Composer Dependencies
if: ${{ steps.validate.outputs.valid == 'true' }}
run: composer install --prefer-dist --no-progress --no-suggest
- name: Setup Node.js
if: ${{ steps.validate.outputs.valid == 'true' }}
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install NPM Dependencies
if: ${{ steps.validate.outputs.valid == 'true' }}
run: npm ci
- name: Build Frontend Assets
if: ${{ steps.validate.outputs.valid == 'true' }}
run: npm run build
- name: Run Tests
if: ${{ steps.validate.outputs.valid == 'true' }}
run: php artisan test
# Job 2: Build and Push Docker Image
build:
runs-on: ubuntu-latest
needs: test
if: github.event_name == 'push'
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Validate Conventional Commit
id: validate
run: |
SUBJECT="$(git log -1 --pretty=%s)"
echo "Commit subject: $SUBJECT"
if echo "$SUBJECT" | grep -Eq '^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .+'; then
echo "valid=true" >> "$GITHUB_OUTPUT"
else
echo "valid=false" >> "$GITHUB_OUTPUT"
fi
- name: Stop if not a Conventional Commit
if: ${{ steps.validate.outputs.valid != 'true' }}
run: |
echo "Latest commit is not a valid Conventional Commit. Skipping build."
exit 0
- name: Set up Docker Buildx
if: ${{ steps.validate.outputs.valid == 'true' }}
uses: docker/setup-buildx-action@v3
- name: Determine Docker Tag
id: docker_tag
if: ${{ steps.validate.outputs.valid == 'true' }}
run: |
if [ "${{ github.ref_name }}" == "main" ]; then
echo "tag=latest" >> "$GITHUB_OUTPUT"
echo "env=production" >> "$GITHUB_OUTPUT"
else
echo "tag=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
echo "env=staging" >> "$GITHUB_OUTPUT"
fi
- name: Build Docker Image
if: ${{ steps.validate.outputs.valid == 'true' }}
uses: docker/build-push-action@v6
with:
context: .
file: ./Dockerfile
push: false
load: true
tags: ${{ env.DOCKER_IMAGE }}:${{ steps.docker_tag.outputs.tag }}
cache-from: type=gha
cache-to: type=gha,mode=max
- name: Save Docker Image
if: ${{ steps.validate.outputs.valid == 'true' }}
run: |
docker save ${{ env.DOCKER_IMAGE }}:${{ steps.docker_tag.outputs.tag }} | gzip > laravel-app.tar.gz
- name: Upload Docker Image Artifact
if: ${{ steps.validate.outputs.valid == 'true' }}
uses: actions/upload-artifact@v4
with:
name: docker-image
path: laravel-app.tar.gz
retention-days: 1
# Job 3: Deploy to Synology NAS
deploy:
runs-on: ubuntu-latest
needs: build
if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Download Docker Image Artifact
uses: actions/download-artifact@v4
with:
name: docker-image
- name: Determine Environment
id: env
run: |
if [ "${{ github.ref_name }}" == "main" ]; then
echo "env=production" >> "$GITHUB_OUTPUT"
else
echo "env=staging" >> "$GITHUB_OUTPUT"
fi
- name: Setup SSH
run: |
mkdir -p ~/.ssh
echo "${{ secrets.SYNOLOGY_SSH_KEY }}" > ~/.ssh/synology_key
chmod 600 ~/.ssh/synology_key
ssh-keyscan -H ${{ secrets.SYNOLOGY_HOST }} >> ~/.ssh/known_hosts
- name: Copy Files to Synology
run: |
# Transfer Docker Image
scp -i ~/.ssh/synology_key laravel-app.tar.gz \
${{ secrets.SYNOLOGY_USER }}@${{ secrets.SYNOLOGY_HOST }}:/volume1/docker/laravel-app/
# Transfer Docker Compose file
scp -i ~/.ssh/synology_key docker-compose.synology.yml \
${{ secrets.SYNOLOGY_USER }}@${{ secrets.SYNOLOGY_HOST }}:/volume1/docker/laravel-app/
# Transfer deployment script
scp -i ~/.ssh/synology_key scripts/deploy-synology.sh \
${{ secrets.SYNOLOGY_USER }}@${{ secrets.SYNOLOGY_HOST }}:/volume1/docker/laravel-app/
- name: Deploy on Synology
run: |
ssh -i ~/.ssh/synology_key \
${{ secrets.SYNOLOGY_USER }}@${{ secrets.SYNOLOGY_HOST }} \
"cd /volume1/docker/laravel-app && chmod +x deploy-synology.sh && ./deploy-synology.sh"
- name: Health Check
run: |
sleep 10 # Wait for container to start
# Check if the app is responding
SYNOLOGY_IP="${{ secrets.SYNOLOGY_HOST }}"
MAX_RETRIES=30
RETRY_COUNT=0
while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
if curl -f -s http://$SYNOLOGY_IP:8080/health > /dev/null 2>&1; then
echo "✅ Application is healthy!"
exit 0
fi
echo "⏳ Waiting for application to be ready... ($RETRY_COUNT/$MAX_RETRIES)"
sleep 5
RETRY_COUNT=$((RETRY_COUNT + 1))
done
echo "❌ Health check failed after $MAX_RETRIES attempts"
exit 1
- name: Cleanup
if: always()
run: |
rm -f ~/.ssh/synology_key
ssh -i ~/.ssh/synology_key \
${{ secrets.SYNOLOGY_USER }}@${{ secrets.SYNOLOGY_HOST }} \
"rm -f /volume1/docker/laravel-app/laravel-app.tar.gz" || true
# Job 4: Notify on Success/Failure (optional)
notify:
runs-on: ubuntu-latest
needs: [test, build, deploy]
if: always()
steps:
- name: Deployment Status
run: |
if [ "${{ needs.deploy.result }}" == "success" ]; then
echo "✅ Deployment to Synology NAS successful!"
echo "🌐 Application available at: http://${{ secrets.SYNOLOGY_HOST }}:8080"
else
echo "❌ Deployment failed. Check the logs for details."
exit 1
fi
.gitignore
+8
View File
@@ -39,6 +39,14 @@ yarn-error.log
/database/*.sqlite /database/*.sqlite
/database/*.sqlite-journal /database/*.sqlite-journal
*.sql.gz *.sql.gz
/backups
# CI/CD & Deployment
.env.synology
.env.gitea-runner
kubeconfig
*.tar.gz
laravel-app.tar.gz
# Backup & Temporary Files # Backup & Temporary Files
*.bak *.bak
CI_CD_README.md
+281
View File
@@ -0,0 +1,281 @@
# CI/CD Automatisierung für Synology NAS
Dieses Projekt ist vollständig für automatisches Deployment auf deiner Synology NAS mit Gitea Actions vorbereitet.
## 🚀 Schnellstart
### 1. Gitea Runner einrichten (einmalig)
```bash
# Auf der Synology NAS
cd /volume1/docker
mkdir gitea-runner
cd gitea-runner
# Environment Datei erstellen
cat > .env << 'EOF'
GITEA_URL=http://your-synology-ip:3000
RUNNER_TOKEN=your_token_from_gitea
RUNNER_NAME=synology-runner
EOF
# Runner starten
docker-compose -f /path/to/docker-compose.gitea-runner.yml up -d
```
**Runner Token generieren:**
1. Gitea öffnen
2. Repository → Settings → Actions → Runners
3. "Create new Runner" klicken
4. Token kopieren und in `.env` einfügen
📖 Detaillierte Anleitung: [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)
### 2. Repository Secrets konfigurieren (einmalig)
In Gitea: **Repository → Settings → Secrets**
| Secret Name | Wert | Beschreibung |
|------------|------|--------------|
| `SYNOLOGY_HOST` | `192.168.1.100` | IP deiner Synology |
| `SYNOLOGY_USER` | `admin` | SSH-Benutzername |
| `SYNOLOGY_SSH_KEY` | `-----BEGIN...` | Private SSH-Key |
| `APP_KEY` | `base64:...` | Laravel APP_KEY |
**SSH-Key erstellen:**
```bash
# Auf der Synology NAS
ssh-keygen -t ed25519 -C "gitea-deploy" -f ~/.ssh/gitea_deploy
cat ~/.ssh/gitea_deploy.pub >> ~/.ssh/authorized_keys
cat ~/.ssh/gitea_deploy # Diesen Key als Secret verwenden
```
### 3. Code pushen und automatisch deployen! 🎉
```bash
git add .
git commit -m "feat: meine neue Funktion"
git push origin main
```
Das wars! Der Rest läuft automatisch:
- ✅ Tests werden ausgeführt
- ✅ Docker Image wird gebaut
- ✅ Deployment auf NAS
- ✅ Health Check
- ✅ Benachrichtigung bei Erfolg/Fehler
## 📁 Wichtige Dateien
| Datei | Beschreibung |
|-------|--------------|
| [`.gitea/workflows/deploy-synology.yml`](.gitea/workflows/deploy-synology.yml) | Gitea Actions Workflow |
| [`docker-compose.synology.yml`](docker-compose.synology.yml) | Docker Compose für Deployment |
| [`scripts/deploy-synology.sh`](scripts/deploy-synology.sh) | Deployment-Script |
| [`.env.synology.example`](.env.synology.example) | Environment-Beispiel |
| [`SYNOLOGY_DEPLOYMENT.md`](SYNOLOGY_DEPLOYMENT.md) | Vollständige Deployment-Doku |
| [`GITEA_RUNNER_SETUP.md`](GITEA_RUNNER_SETUP.md) | Gitea Runner Setup-Anleitung |
## 🔄 Workflow-Prozess
```
1. Developer pushed Code zu Gitea
↓
2. Gitea Actions Workflow startet
↓
3. Tests laufen (Pest)
↓
4. Docker Image wird gebaut
↓
5. Image wird zur Synology NAS übertragen
↓
6. Deployment-Script läuft auf NAS
↓
7. Container werden aktualisiert
↓
8. Migrationen & Cache-Optimierung
↓
9. Health Check
↓
10. ✅ Deployment erfolgreich!
```
## 🎯 Features
### Automatisierte Tests
- PHP-Tests mit Pest
- Frontend-Build-Validierung
- Nur erfolgreiche Builds werden deployed
### Intelligentes Deployment
- Automatisches Backup vor Deployment
- Rollback bei Fehlern
- Health Checks nach Deployment
- Zero-Downtime durch Docker
### Branch-spezifisches Deployment
- `main` → Production (Port 8080)
- `develop` → Staging (Port 8081)
- Feature-Branches → Nur Tests
### Conventional Commits
Der Workflow akzeptiert nur Conventional Commits:
- `feat:` - Neue Features
- `fix:` - Bugfixes
- `docs:` - Dokumentation
- `chore:` - Wartung
- `refactor:` - Code-Refactoring
- `test:` - Tests
- `ci:` - CI/CD Änderungen
**Beispiel:**
```bash
git commit -m "feat: add user authentication"
git commit -m "fix: resolve database connection issue"
```
## 🔍 Monitoring
### Workflow Status prüfen
**In Gitea:**
1. Repository öffnen
2. Tab "Actions" anklicken
3. Alle Runs mit Status sehen
**Logs ansehen:**
- Klicke auf einen Run
- Klicke auf einen Job (test/build/deploy)
- Sieh detaillierte Logs
### Container Logs
```bash
# Auf der Synology NAS via SSH
docker logs -f laravel_app
docker logs -f laravel_postgres
```
### Health Endpoint
```bash
curl http://your-synology-ip:8080/health
```
Response:
```json
{
"status": "healthy",
"timestamp": "2025-12-17T10:30:00Z",
"app": "Laravel",
"env": "production"
}
```
## 🛠 Manuelle Befehle
### Manuelles Deployment
```bash
# Auf der Synology NAS
cd /volume1/docker/laravel-app
./scripts/deploy-synology.sh
```
### Container verwalten
```bash
# Status prüfen
docker-compose -f docker-compose.synology.yml ps
# Logs ansehen
docker-compose -f docker-compose.synology.yml logs -f
# Neustart
docker-compose -f docker-compose.synology.yml restart
# Stoppen
docker-compose -f docker-compose.synology.yml down
```
### Laravel Artisan
```bash
# Migrationen
docker exec laravel_app php artisan migrate
# Cache leeren
docker exec laravel_app php artisan cache:clear
# Shell öffnen
docker exec -it laravel_app sh
```
## 🐛 Troubleshooting
### Workflow startet nicht
**Prüfen:**
1. Runner Status in Gitea → Settings → Actions → Runners
2. Commit-Message ist Conventional Commit Format
3. Branch ist `main` oder `develop`
**Lösung:**
```bash
# Runner neu starten
docker restart gitea-runner
# Runner Logs prüfen
docker logs gitea-runner
```
### Deployment schlägt fehl
**Prüfen:**
1. SSH-Verbindung zur NAS funktioniert
2. Alle Secrets sind korrekt gesetzt
3. Deployment-Script ist executable
**Lösung:**
```bash
# SSH-Key testen
ssh -i ~/.ssh/gitea_deploy admin@your-synology-ip
# Permissions prüfen
chmod +x scripts/deploy-synology.sh
```
### Health Check fehlschlägt
**Prüfen:**
1. Container läuft: `docker ps | grep laravel_app`
2. Logs: `docker logs laravel_app`
3. Netzwerk: `curl http://localhost:8080/health`
**Lösung:**
```bash
# Container neu starten
docker-compose -f docker-compose.synology.yml restart
# .env prüfen
docker exec laravel_app cat .env.synology
```
## 📚 Weitere Dokumentation
- **Deployment Details:** [SYNOLOGY_DEPLOYMENT.md](SYNOLOGY_DEPLOYMENT.md)
- **Gitea Runner Setup:** [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)
- **Workflow Konfiguration:** [.gitea/workflows/deploy-synology.yml](.gitea/workflows/deploy-synology.yml)
- **Deployment Script:** [scripts/deploy-synology.sh](scripts/deploy-synology.sh)
## 🎉 Das wars!
Nach der einmaligen Einrichtung läuft alles automatisch:
1. Code schreiben
2. Commit & Push
3. Warten bis Deployment fertig ist
4. Anwendung ist live! 🚀
**Happy Deploying!** 🎊
DEPLOYMENT_FILES_OVERVIEW.md
+210
View File
@@ -0,0 +1,210 @@
# Deployment Files Übersicht
Diese Datei gibt einen Überblick über alle Dateien, die für das automatisierte Deployment auf deiner Synology NAS erstellt wurden.
## 📋 Erstelle Dateien
### 1. CI/CD Workflow
- **`.gitea/workflows/deploy-synology.yml`**
- Gitea Actions Workflow für automatisches Build & Deployment
- Führt Tests aus, baut Docker Image, deployt auf NAS
- Triggert bei Push auf `main` oder `develop`
### 2. Docker Konfiguration
- **`docker-compose.synology.yml`**
- Docker Compose für Synology NAS Deployment
- Definiert Laravel App + PostgreSQL Datenbank
- Mit persistenten Volumes und Health Checks
- **`docker-compose.gitea-runner.yml`**
- Docker Compose für Gitea Runner
- Ermöglicht automatische Workflows
- **`Dockerfile`**
- Bereits vorhanden, wird verwendet für Image-Build
- Multi-stage Build für optimale Image-Größe
### 3. Environment Konfiguration
- **`.env.synology.example`**
- Beispiel-Environment für Synology Deployment
- Muss kopiert werden zu `.env.synology`
- Enthält alle notwendigen Variablen
- **`.env.gitea-runner.example`**
- Beispiel-Environment für Gitea Runner
- Muss kopiert werden zu `.env.gitea-runner`
### 4. Deployment Scripts
- **`scripts/deploy-synology.sh`**
- Automatisches Deployment-Script
- Läuft auf der Synology NAS
- Handhabt Backup, Deployment, Rollback, Health Checks
### 5. Dokumentation
- **`SYNOLOGY_DEPLOYMENT.md`**
- Vollständige Anleitung für manuelles Deployment
- Inklusive CI/CD Setup Abschnitt
- Troubleshooting Tipps
- **`GITEA_RUNNER_SETUP.md`**
- Detaillierte Anleitung für Gitea Runner Setup
- Secrets-Konfiguration
- Monitoring & Troubleshooting
- **`CI_CD_README.md`**
- Schnellstart-Anleitung für CI/CD
- Übersicht über alle Features
- Wichtige Befehle
- **`DEPLOYMENT_FILES_OVERVIEW.md`** (diese Datei)
- Übersicht über alle erstellten Dateien
### 6. Application Code
- **`routes/web.php`**
- Health Check Endpoint hinzugefügt (`/health`)
- Wird für automatische Health Checks verwendet
### 7. Git Konfiguration
- **`.gitignore`**
- Erweitert um CI/CD spezifische Dateien
- `.env.synology` und `.env.gitea-runner` ignoriert
- Build-Artefakte ignoriert
## 🔧 Verwendung der Dateien
### Einmalige Einrichtung
1. **Gitea Runner deployen:**
```bash
# Auf Synology NAS
cp .env.gitea-runner.example .env.gitea-runner
# Bearbeite .env.gitea-runner mit deinen Werten
docker-compose -f docker-compose.gitea-runner.yml up -d
```
2. **Repository Secrets in Gitea setzen:**
- `SYNOLOGY_HOST`
- `SYNOLOGY_USER`
- `SYNOLOGY_SSH_KEY`
- `APP_KEY`
3. **Workflow-Dateien committen:**
```bash
git add .gitea/
git commit -m "ci: add automated deployment"
git push origin main
```
### Manuelles Deployment
Falls du manuell deployen möchtest (ohne CI/CD):
```bash
# Auf Synology NAS
cd /volume1/docker/laravel-app
cp .env.synology.example .env.synology
# Bearbeite .env.synology
docker-compose -f docker-compose.synology.yml up -d --build
```
## 📊 Datei-Abhängigkeiten
```
.gitea/workflows/deploy-synology.yml
├── docker-compose.synology.yml
├── scripts/deploy-synology.sh
├── .env.synology (zu erstellen)
└── Dockerfile
docker-compose.gitea-runner.yml
└── .env.gitea-runner (zu erstellen)
```
## ✅ Checkliste für Deployment
### Vor dem ersten Deployment:
- [ ] Gitea Runner deployed (`docker-compose.gitea-runner.yml`)
- [ ] Runner in Gitea registriert
- [ ] Repository Secrets gesetzt
- [ ] `.env.synology` auf NAS erstellt und konfiguriert
- [ ] SSH-Keys für Deployment eingerichtet
- [ ] Projekt-Verzeichnis auf NAS: `/volume1/docker/laravel-app`
### Vor jedem Push:
- [ ] Tests lokal ausgeführt (`php artisan test`)
- [ ] Conventional Commit Message verwendet
- [ ] Code reviewed
### Nach dem Deployment:
- [ ] Workflow Status in Gitea Actions überprüft
- [ ] Health Check erfolgreich: `curl http://nas-ip:8080/health`
- [ ] Anwendung erreichbar: `http://nas-ip:8080`
- [ ] Logs prüfen: `docker logs laravel_app`
## 🔐 Sicherheit
### Dateien die NICHT committet werden sollten:
- `.env.synology` - Enthält Produktions-Secrets
- `.env.gitea-runner` - Enthält Runner-Token
- `kubeconfig` - Falls verwendet
- `*.tar.gz` - Build-Artefakte
- SSH Private Keys
Diese Dateien sind bereits in `.gitignore` eingetragen!
### Dateien die committet werden sollten:
- `.env.synology.example` - Template für andere Entwickler
- `.env.gitea-runner.example` - Template für Runner
- Alle `docker-compose*.yml` Dateien
- Alle Dokumentations-Dateien
- Workflow-Dateien in `.gitea/workflows/`
- Deployment-Scripts in `scripts/`
## 🚀 Nächste Schritte
1. **Lies die Dokumentation:**
- Start mit [CI_CD_README.md](CI_CD_README.md) für Schnellstart
- Dann [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md) für Runner-Setup
- Bei Problemen: [SYNOLOGY_DEPLOYMENT.md](SYNOLOGY_DEPLOYMENT.md)
2. **Setup durchführen:**
- Folge der Anleitung in [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)
- Konfiguriere Secrets in Gitea
- Teste mit einem Push
3. **Deployment testen:**
- Mache eine kleine Änderung
- Committe mit Conventional Commit
- Push und beobachte Workflow in Gitea Actions
4. **Optional: Erweitere Workflow:**
- Füge Notifications hinzu (Email, Telegram, Discord)
- Konfiguriere mehrere Environments (Staging, Production)
- Füge weitere Tests hinzu
## 📝 Hinweise
- Alle Scripts sind für **Synology DSM 7.x** optimiert
- Docker und Docker Compose müssen auf der NAS installiert sein
- Gitea Actions muss in Gitea aktiviert sein
- PHP 8.4 und Laravel 12 werden verwendet
## 🆘 Support
Bei Fragen oder Problemen:
1. Prüfe die Troubleshooting-Sektionen in den Dokumentations-Dateien
2. Prüfe Logs: `docker logs gitea-runner` und `docker logs laravel_app`
3. Verifiziere alle Secrets und Environment-Variablen
4. Stelle sicher, dass alle Ports verfügbar sind
---
**Erstellt am:** 2025-12-17
**Version:** 1.0
**Für:** Synology NAS Deployment mit Gitea Actions
GITEA_RUNNER_SETUP.md
+411
View File
@@ -0,0 +1,411 @@
# Gitea Runner Setup auf Synology NAS
Diese Anleitung erklärt, wie du einen Gitea Actions Runner auf deiner Synology NAS einrichtest, um automatische Deployments durchzuführen.
## Voraussetzungen
- Gitea läuft auf deiner Synology NAS
- Docker ist auf der Synology NAS installiert
- SSH-Zugriff auf die Synology NAS
- Portainer läuft (optional, aber empfohlen für Container-Management)
## Option 1: Gitea Runner mit Docker Compose (empfohlen)
### 1. Runner Docker Compose Datei erstellen
Erstelle eine Datei `/volume1/docker/gitea-runner/docker-compose.yml`:
```yaml
version: "3.9"
services:
runner:
image: gitea/act_runner:latest
container_name: gitea-runner
restart: unless-stopped
environment:
- GITEA_INSTANCE_URL=http://your-gitea-url:3000
- GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
- GITEA_RUNNER_NAME=synology-runner
- GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye
volumes:
- ./data:/data
- /var/run/docker.sock:/var/run/docker.sock
networks:
- gitea-network
networks:
gitea-network:
external: true
```
### 2. Runner Token generieren
1. Öffne deine Gitea-Instanz im Browser
2. Navigiere zu deinem Repository
3. Gehe zu **Settings** → **Actions** → **Runners**
4. Klicke auf **Create new Runner**
5. Kopiere den generierten Token
### 3. Environment Variables setzen
Erstelle eine `.env` Datei im selben Verzeichnis:
```env
RUNNER_TOKEN=dein_gitea_runner_token_hier
```
### 4. Runner starten
```bash
cd /volume1/docker/gitea-runner
docker-compose up -d
```
### 5. Runner verifizieren
```bash
# Logs anschauen
docker logs -f gitea-runner
# Status prüfen
docker ps | grep gitea-runner
```
In Gitea solltest du nun unter **Settings** → **Actions** → **Runners** deinen registrierten Runner sehen.
## Option 2: Runner direkt in Portainer deployen
### 1. In Portainer einloggen
Öffne Portainer: `http://your-synology-ip:9000`
### 2. Stack erstellen
1. Gehe zu **Stacks** → **+ Add stack**
2. Name: `gitea-runner`
3. Wähle **Web editor**
4. Füge die obige docker-compose.yml ein
### 3. Environment Variables
Füge folgende Environment Variable hinzu:
- **RUNNER_TOKEN**: Dein Gitea Runner Token
### 4. Deploy
Klicke auf **Deploy the stack**
## Runner Konfiguration
### Custom Runner Labels
Um spezifische Workflows auszuführen, kannst du Custom Labels hinzufügen:
```yaml
environment:
- GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye,ubuntu-22.04:docker://ubuntu:22.04,php-8.4:docker://php:8.4-cli
```
### Mehrere Runner
Für parallele Builds kannst du mehrere Runner starten:
```yaml
services:
runner-1:
image: gitea/act_runner:latest
container_name: gitea-runner-1
# ... config ...
runner-2:
image: gitea/act_runner:latest
container_name: gitea-runner-2
# ... config ...
```
## Repository Secrets konfigurieren
Um das automatische Deployment zu ermöglichen, musst du Secrets in deinem Gitea-Repository hinterlegen:
### 1. In Gitea Repository Settings
1. Gehe zu deinem Repository
2. Klicke auf **Settings** → **Secrets**
3. Füge folgende Secrets hinzu:
| Secret Name | Beschreibung | Beispiel |
|------------|--------------|----------|
| `SYNOLOGY_HOST` | IP oder Hostname deiner Synology | `192.168.1.100` |
| `SYNOLOGY_USER` | SSH-Benutzername | `admin` |
| `SYNOLOGY_SSH_KEY` | Privater SSH-Key für Zugriff | `-----BEGIN OPENSSH PRIVATE KEY-----...` |
| `APP_KEY` | Laravel Application Key | `base64:xyz...` |
### 2. SSH-Key generieren (falls nicht vorhanden)
Auf deiner Synology NAS:
```bash
# SSH-Key-Pair generieren
ssh-keygen -t ed25519 -C "gitea-runner@synology" -f ~/.ssh/gitea_deploy
# Public Key zum authorized_keys hinzufügen
cat ~/.ssh/gitea_deploy.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
# Private Key anzeigen (für Secret)
cat ~/.ssh/gitea_deploy
```
Kopiere den **gesamten** Private Key (inklusive `-----BEGIN` und `-----END` Zeilen) und füge ihn als `SYNOLOGY_SSH_KEY` Secret hinzu.
### 3. Secrets verifizieren
Stelle sicher, dass alle benötigten Secrets gesetzt sind:
```bash
# In Gitea Repository Settings → Secrets
✅ SYNOLOGY_HOST
✅ SYNOLOGY_USER
✅ SYNOLOGY_SSH_KEY
✅ APP_KEY
```
## Workflow aktivieren
### 1. Workflow-Datei pushen
```bash
# Lokal im Projekt
git add .gitea/workflows/deploy-synology.yml
git commit -m "ci: add automated deployment workflow"
git push origin main
```
### 2. Workflow ausführen
Gitea Actions wird automatisch bei jedem Push auf `main` oder `develop` ausgelöst.
### 3. Workflow Status prüfen
1. Gehe zu deinem Repository in Gitea
2. Klicke auf **Actions**
3. Du siehst alle Workflow-Runs mit Status (Success/Failure)
4. Klicke auf einen Run, um Details und Logs zu sehen
## Workflow manuell auslösen
Falls du den Workflow manuell starten möchtest:
### 1. Workflow-Datei erweitern
Füge in `.gitea/workflows/deploy-synology.yml` hinzu:
```yaml
on:
push:
branches:
- main
- develop
workflow_dispatch: # Ermöglicht manuelles Auslösen
```
### 2. Manuell auslösen
1. Gehe zu **Actions** in deinem Repository
2. Wähle den Workflow aus
3. Klicke auf **Run workflow**
## Monitoring & Logs
### Runner Logs
```bash
# Live Logs
docker logs -f gitea-runner
# Letzte 100 Zeilen
docker logs --tail 100 gitea-runner
```
### Workflow Logs
In Gitea UI:
1. **Actions** Tab
2. Wähle einen Workflow Run
3. Klicke auf die einzelnen Jobs, um Logs zu sehen
### Deployment Logs auf Synology
```bash
# Laravel App Logs
docker logs -f laravel_app
# Deployment Script Logs
# Diese werden in der Workflow-Ausgabe angezeigt
```
## Troubleshooting
### Problem: Runner verbindet sich nicht
```bash
# Logs prüfen
docker logs gitea-runner
# Runner neu registrieren
docker-compose down
docker-compose up -d
```
### Problem: Workflow startet nicht
1. **Runner Status prüfen**: Gehe zu Repository → Settings → Actions → Runners
2. **Runner Labels prüfen**: Stelle sicher, dass `runs-on: ubuntu-latest` mit den Runner Labels übereinstimmt
3. **Secrets prüfen**: Alle benötigten Secrets müssen gesetzt sein
### Problem: SSH-Verbindung fehlschlägt
```bash
# SSH-Key Permissions prüfen
chmod 600 ~/.ssh/gitea_deploy
chmod 644 ~/.ssh/gitea_deploy.pub
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
# SSH-Verbindung testen (lokal auf der NAS)
ssh -i ~/.ssh/gitea_deploy admin@localhost
```
### Problem: Deployment schlägt fehl
```bash
# Prüfe deployment script permissions
cd /volume1/docker/laravel-app
ls -la deploy-synology.sh
# Mache es executable
chmod +x deploy-synology.sh
# Teste deployment script manuell
./deploy-synology.sh
```
### Problem: Health Check fehlschlägt
```bash
# Prüfe ob Container läuft
docker ps | grep laravel_app
# Prüfe Logs
docker logs laravel_app
# Teste Health Endpoint manuell
curl http://localhost:8080/health
```
## Best Practices
### 1. Separate Runner für Production und Staging
```yaml
services:
runner-production:
environment:
- GITEA_RUNNER_LABELS=production:docker://ubuntu:22.04
runner-staging:
environment:
- GITEA_RUNNER_LABELS=staging:docker://ubuntu:22.04
```
Im Workflow:
```yaml
jobs:
deploy-production:
runs-on: production
if: github.ref == 'refs/heads/main'
```
### 2. Workflow nur für Conventional Commits
Der aktuelle Workflow filtert bereits nach Conventional Commits:
- `feat:` - Neue Features
- `fix:` - Bugfixes
- `docs:` - Dokumentation
- `chore:` - Wartungsarbeiten
- etc.
### 3. Notifications
Erweitere den Workflow um Benachrichtigungen:
```yaml
- name: Send Notification
if: always()
run: |
# Telegram, Discord, Email, etc.
curl -X POST https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage \
-d chat_id=${{ secrets.TELEGRAM_CHAT_ID }} \
-d text="Deployment status: ${{ job.status }}"
```
### 4. Rollback-Strategie
Im deployment script ist bereits ein Backup-Mechanismus implementiert:
- Datenbank-Backups vor jedem Deployment
- Letzte 5 Backups werden aufbewahrt
- Automatischer Rollback bei Fehlern
## Erweiterte Konfiguration
### Multi-Stage Deployments
Für staging und production environments:
```yaml
jobs:
deploy-staging:
if: github.ref == 'refs/heads/develop'
# ... deploy to staging ...
deploy-production:
if: github.ref == 'refs/heads/main'
needs: [test, deploy-staging]
# ... deploy to production ...
```
### Caching
Um Build-Zeiten zu verkürzen:
```yaml
- name: Cache Composer
uses: actions/cache@v3
with:
path: vendor
key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}
- name: Cache NPM
uses: actions/cache@v3
with:
path: node_modules
key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
```
## Weitere Ressourcen
- [Gitea Actions Dokumentation](https://docs.gitea.com/usage/actions/overview)
- [Act Runner Dokumentation](https://gitea.com/gitea/act_runner)
- [Docker Compose Dokumentation](https://docs.docker.com/compose/)
## Support
Bei Problemen:
1. Prüfe Runner Logs: `docker logs gitea-runner`
2. Prüfe Workflow Logs in Gitea Actions Tab
3. Verifiziere alle Secrets sind korrekt gesetzt
4. Teste SSH-Verbindung zur Synology manuell
SYNOLOGY_DEPLOYMENT.md
+435
View File
@@ -0,0 +1,435 @@
# Synology NAS Deployment Anleitung
Diese Anleitung beschreibt, wie du diese Laravel-Anwendung auf deiner Synology NAS mit Portainer deployen kannst.
## 📋 Inhaltsverzeichnis
1. [Voraussetzungen](#voraussetzungen)
2. [Manuelles Deployment](#-vorbereitung)
3. [Automatisches CI/CD Deployment](#-automatisches-deployment-mit-gitea-actions)
4. [Monitoring & Wartung](#-monitoring--wartung)
5. [Troubleshooting](#-troubleshooting)
## Voraussetzungen
- Synology NAS mit Docker-Unterstützung
- Portainer läuft bereits auf deiner NAS
- SSH-Zugriff auf die Synology NAS (optional, aber empfohlen)
- Mindestens 2GB freier RAM
- Mindestens 5GB freier Speicherplatz
- (Optional) Gitea für automatisches CI/CD Deployment
## 📦 Vorbereitung
### 1. Projekt-Dateien auf die NAS übertragen
Es gibt mehrere Möglichkeiten, die Dateien auf deine Synology zu übertragen:
#### Option A: Via Git (empfohlen)
```bash
# SSH auf die Synology NAS
ssh admin@your-synology-ip
# Navigiere zu einem geeigneten Verzeichnis (z.B. /volume1/docker/laravel)
cd /volume1/docker
git clone <dein-repository-url> laravel-app
cd laravel-app
```
#### Option B: Via File Station
1. Öffne die Synology File Station
2. Erstelle einen Ordner: `/docker/laravel-app`
3. Lade alle Projekt-Dateien in diesen Ordner hoch
#### Option C: Via rsync/scp
```bash
# Vom lokalen Rechner aus
rsync -avz --exclude 'node_modules' --exclude 'vendor' \
/Users/sebastianfrohlich/Herd/frontend/ \
admin@your-synology-ip:/volume1/docker/laravel-app/
```
### 2. Umgebungsvariablen konfigurieren
```bash
# SSH auf der NAS
cd /volume1/docker/laravel-app
# Kopiere die Synology-Beispiel-Datei
cp .env.synology.example .env.synology
# Bearbeite die Datei mit deinen spezifischen Einstellungen
nano .env.synology
```
**Wichtige Anpassungen in `.env.synology`:**
```env
# Ersetze mit deiner Synology IP-Adresse
APP_URL=http://192.168.1.100:8080
# Setze APP_DEBUG auf false für Produktion
APP_DEBUG=false
# Generiere einen neuen APP_KEY (wichtig für Sicherheit!)
# Dies kann später mit: docker exec laravel_app php artisan key:generate gemacht werden
# PostgreSQL Passwort - ändere dies!
DB_PASSWORD2=dein_sicheres_passwort_hier
```
## 🚀 Deployment mit Portainer
### Methode 1: Docker Compose Stack (empfohlen)
1. **Öffne Portainer** in deinem Browser: `http://your-synology-ip:9000`
2. **Navigiere zu "Stacks"**:
- Klicke auf "Stacks" im linken Menü
- Klicke auf "+ Add stack"
3. **Stack konfigurieren**:
- **Name**: `laravel-app`
- **Build method**: Wähle "Repository"
- **Repository URL**: Gib deine Git-Repository-URL ein (falls vorhanden)
- Oder wähle "Upload" und lade `docker-compose.synology.yml` hoch
- Oder wähle "Web editor" und kopiere den Inhalt von `docker-compose.synology.yml`
4. **Umgebungsvariablen setzen**:
Klicke auf "Add an environment variable" und füge folgende Variablen hinzu:
```
APP_NAME=Laravel
APP_ENV=production
APP_KEY=base64:L9RVZ3pNFyAvTbMqicT1rL5GbgE+7lJerkU9wyc95H8=
APP_DEBUG=false
APP_URL=http://your-synology-ip:8080
DB_CONNECTION2=pgsql
DB_HOST2=postgres
DB_PORT2=5432
DB_DATABASE2=ingest_db
DB_USERNAME2=ingest_user
DB_PASSWORD2=dein_sicheres_passwort
```
5. **Stack deployen**:
- Klicke auf "Deploy the stack"
- Warte, bis der Build-Prozess abgeschlossen ist (kann 5-10 Minuten dauern)
### Methode 2: Build und Deploy manuell via SSH
```bash
# SSH auf die Synology
ssh admin@your-synology-ip
# Navigiere zum Projekt-Verzeichnis
cd /volume1/docker/laravel-app
# Baue das Docker Image
docker build -t laravel-app:latest .
# Starte die Services mit docker-compose
docker-compose -f docker-compose.synology.yml up -d
```
## 🔍 Verifikation
### 1. Überprüfe den Container-Status
In Portainer:
- Gehe zu "Containers"
- Du solltest zwei laufende Container sehen:
- `laravel_app` (Status: running, Port: 0.0.0.0:8080->80/tcp)
- `laravel_postgres` (Status: running, Port: 5432/tcp)
Via SSH:
```bash
docker ps
```
### 2. Überprüfe die Logs
In Portainer:
- Klicke auf den Container `laravel_app`
- Wähle "Logs"
- Du solltest keine Fehler sehen
Via SSH:
```bash
# Laravel App Logs
docker logs laravel_app
# PostgreSQL Logs
docker logs laravel_postgres
```
### 3. Teste die Anwendung
Öffne deinen Browser und navigiere zu:
```
http://your-synology-ip:8080
```
Du solltest die Laravel-Anwendung sehen!
## 🔧 Nützliche Befehle
### Artisan-Befehle ausführen
```bash
# Laravel Cache leeren
docker exec laravel_app php artisan cache:clear
# Neuen APP_KEY generieren
docker exec laravel_app php artisan key:generate
# Migrationen ausführen
docker exec laravel_app php artisan migrate
# Seeder ausführen
docker exec laravel_app php artisan db:seed
```
### Container neustarten
Via Portainer:
- Gehe zu "Containers"
- Wähle den Container aus
- Klicke auf "Restart"
Via SSH:
```bash
docker-compose -f docker-compose.synology.yml restart
```
### Container stoppen und entfernen
Via Portainer:
- Gehe zu "Stacks"
- Wähle den Stack "laravel-app"
- Klicke auf "Stop" oder "Delete"
Via SSH:
```bash
docker-compose -f docker-compose.synology.yml down
# Mit Volumes löschen (Achtung: Löscht die Datenbank!)
docker-compose -f docker-compose.synology.yml down -v
```
### Logs live verfolgen
```bash
# Alle Container
docker-compose -f docker-compose.synology.yml logs -f
# Nur Laravel App
docker logs -f laravel_app
# Nur PostgreSQL
docker logs -f laravel_postgres
```
## 🔐 Sicherheitshinweise
1. **APP_KEY ändern**: Generiere einen neuen APP_KEY für die Produktion:
```bash
docker exec laravel_app php artisan key:generate
```
2. **Datenbank-Passwort**: Ändere das Standard-PostgreSQL-Passwort in `.env.synology`
3. **APP_DEBUG**: Stelle sicher, dass `APP_DEBUG=false` in der Produktion
4. **Firewall**: Konfiguriere die Synology-Firewall, um nur benötigte Ports zu öffnen
5. **SSL/HTTPS**: Für den Produktionsbetrieb solltest du einen Reverse Proxy (z.B. Synology DSM Reverse Proxy) mit SSL-Zertifikat einrichten
## 🌐 Reverse Proxy einrichten (optional, aber empfohlen)
Für den Zugriff über eine Domain mit HTTPS:
1. **In Synology DSM**:
- Gehe zu "Systemsteuerung" → "Anmeldungsportal" → "Erweitert"
- Klicke auf "Reverse Proxy" → "Erstellen"
2. **Konfiguration**:
- **Protokoll**: HTTPS
- **Hostname**: your-domain.com
- **Port**: 443
- **Zielprotokoll**: HTTP
- **Zielhost**: localhost
- **Zielport**: 8080
3. **SSL-Zertifikat**:
- Gehe zu "Systemsteuerung" → "Sicherheit" → "Zertifikat"
- Füge ein Let's Encrypt-Zertifikat hinzu
## 📊 Monitoring & Wartung
### Container-Ressourcen überwachen
In Portainer:
- Gehe zu "Containers"
- Wähle einen Container
- Klicke auf "Stats" für Echtzeit-Metriken (CPU, RAM, Netzwerk)
### Backup
```bash
# PostgreSQL Datenbank sichern
docker exec laravel_postgres pg_dump -U ingest_user ingest_db > backup_$(date +%Y%m%d).sql
# Gesamten Stack sichern (inkl. Volumes)
docker run --rm \
-v laravel-app_postgres-data:/data \
-v /volume1/docker/backups:/backup \
alpine tar czf /backup/postgres-backup-$(date +%Y%m%d).tar.gz /data
```
### Updates
```bash
# Projekt-Code aktualisieren (wenn via Git)
cd /volume1/docker/laravel-app
git pull
# Neu bauen und deployen
docker-compose -f docker-compose.synology.yml up -d --build
# Migrationen ausführen
docker exec laravel_app php artisan migrate --force
```
## ❓ Troubleshooting
### Problem: Container startet nicht
```bash
# Logs prüfen
docker logs laravel_app
# Container interaktiv starten für Debugging
docker exec -it laravel_app sh
```
### Problem: Datenbank-Verbindung fehlgeschlagen
```bash
# PostgreSQL-Container prüfen
docker exec laravel_postgres pg_isready -U ingest_user
# Umgebungsvariablen prüfen
docker exec laravel_app env | grep DB_
```
### Problem: Permissions-Fehler
```bash
# Storage-Permissions korrigieren
docker exec laravel_app chmod -R 775 storage bootstrap/cache
docker exec laravel_app chown -R nginx:nginx storage bootstrap/cache
```
### Problem: Port bereits belegt
Wenn Port 8080 bereits verwendet wird:
1. Öffne `docker-compose.synology.yml`
2. Ändere die Port-Mapping: `"8081:80"` statt `"8080:80"`
3. Aktualisiere `APP_URL` in `.env.synology` entsprechend
## 🤖 Automatisches Deployment mit Gitea Actions
Wenn du Gitea auf deiner Synology NAS verwendest, kannst du den gesamten Build- und Deployment-Prozess automatisieren!
### Vorteile von CI/CD
- ✅ Automatischer Build bei jedem Git Push
- ✅ Automatische Tests vor Deployment
- ✅ Automatisches Deployment auf die NAS
- ✅ Rollback bei Fehlern
- ✅ Keine manuellen Schritte mehr nötig
### Quick Start
1. **Gitea Runner einrichten**
- Siehe detaillierte Anleitung: [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md)
- Kurz: Runner Docker Container auf NAS deployen
- Runner in Gitea registrieren
2. **Repository Secrets konfigurieren**
Gehe in Gitea zu: **Repository → Settings → Secrets**
Füge folgende Secrets hinzu:
```
SYNOLOGY_HOST=192.168.1.100
SYNOLOGY_USER=admin
SYNOLOGY_SSH_KEY=<dein-ssh-private-key>
APP_KEY=<dein-laravel-app-key>
```
3. **Workflow pushen**
Der Workflow in [`.gitea/workflows/deploy-synology.yml`](.gitea/workflows/deploy-synology.yml) ist bereits vorkonfiguriert.
```bash
git add .gitea/workflows/deploy-synology.yml
git commit -m "ci: add automated deployment workflow"
git push origin main
```
4. **Automatisches Deployment genießen! 🎉**
Bei jedem Push auf `main` oder `develop`:
- Tests werden ausgeführt
- Docker Image wird gebaut
- Deployment auf NAS erfolgt automatisch
- Health Check verifiziert Deployment
### Workflow-Ablauf
```mermaid
graph LR
A[Git Push] --> B[Run Tests]
B --> C{Tests OK?}
C -->|Ja| D[Build Docker Image]
C -->|Nein| E[Abbruch]
D --> F[Transfer zu NAS]
F --> G[Deploy auf NAS]
G --> H[Health Check]
H --> I{Healthy?}
I -->|Ja| J[✅ Success]
I -->|Nein| K[Rollback]
```
### Workflow überwachen
1. Gehe zu deinem Repository in Gitea
2. Klicke auf **Actions**
3. Siehe alle Workflow-Runs mit Status
4. Klicke auf einen Run für Details und Logs
### Erweiterte Konfiguration
Weitere Details zur CI/CD-Konfiguration findest du in:
- [GITEA_RUNNER_SETUP.md](GITEA_RUNNER_SETUP.md) - Detaillierte Runner-Setup Anleitung
- [`.gitea/workflows/deploy-synology.yml`](.gitea/workflows/deploy-synology.yml) - Workflow-Konfiguration
- [`scripts/deploy-synology.sh`](scripts/deploy-synology.sh) - Deployment-Script
## 📝 Weitere Ressourcen
- [Laravel Dokumentation](https://laravel.com/docs)
- [Docker Dokumentation](https://docs.docker.com/)
- [Portainer Dokumentation](https://docs.portainer.io/)
- [Synology Docker Anleitung](https://www.synology.com/en-us/dsm/packages/Docker)
- [Gitea Actions Dokumentation](https://docs.gitea.com/usage/actions/overview)
## 🆘 Support
Bei Problemen:
1. Prüfe die Container-Logs
2. Überprüfe die Umgebungsvariablen
3. Stelle sicher, dass alle Ports verfügbar sind
4. Prüfe die Synology-Firewall-Einstellungen
5. Bei CI/CD: Prüfe Gitea Actions Logs und Runner Status
backup_backend_20251203_101741.dump
BIN
View File
Binary file not shown.
backup_devbackend_20251203_103857.dump
BIN
View File
Binary file not shown.
backup_public_20251203_101723.dump
BIN
View File
Binary file not shown.
config/database.php
+10 -10
View File
@@ -86,10 +86,10 @@ return [
'driver' => 'pgsql', 'driver' => 'pgsql',
'url' => env('DB_URL'), 'url' => env('DB_URL'),
'host' => env('DB_HOST2', '127.0.0.1'), 'host' => env('DB_HOST2', '127.0.0.1'),
'port' => env('DB_PORT2', '5433'), 'port' => env('DB_PORT2', '5432'),
'database' => env('DB_DATABASE2', 'risk_ingest_db'), 'database' => env('DB_DATABASE2', 'ingest_db'),
'username' => env('DB_USERNAME2', 'risk_ingest_user'), 'username' => env('DB_USERNAME2', 'ingest_user'),
'password' => env('DB_PASSWORD2', ''), 'password' => env('DB_PASSWORD2', 'ingest_pwd'),
'charset' => env('DB_CHARSET', 'utf8'), 'charset' => env('DB_CHARSET', 'utf8'),
'prefix' => '', 'prefix' => '',
'prefix_indexes' => true, 'prefix_indexes' => true,
@@ -101,9 +101,9 @@ return [
'driver' => env('DB_CONNECTION2'), 'driver' => env('DB_CONNECTION2'),
'host' => env('DB_HOST2', '127.0.0.1'), 'host' => env('DB_HOST2', '127.0.0.1'),
'port' => env('DB_PORT2', '5432'), 'port' => env('DB_PORT2', '5432'),
'database' => env('DB_DATABASE2', 'laravel'), 'database' => env('DB_DATABASE2', 'ingest_db'),
'username' => env('DB_USERNAME2', 'root'), 'username' => env('DB_USERNAME2', 'ingest_user'),
'password' => env('DB_PASSWORD2', ''), 'password' => env('DB_PASSWORD2', 'ingest_pwd'),
'charset' => env('DB_CHARSET', 'utf8'), 'charset' => env('DB_CHARSET', 'utf8'),
'prefix' => '', 'prefix' => '',
'prefix_indexes' => true, 'prefix_indexes' => true,
@@ -115,9 +115,9 @@ return [
'driver' => env('DB_CONNECTION2'), 'driver' => env('DB_CONNECTION2'),
'host' => env('DB_HOST2', '127.0.0.1'), 'host' => env('DB_HOST2', '127.0.0.1'),
'port' => env('DB_PORT2', '5432'), 'port' => env('DB_PORT2', '5432'),
'database' => env('DB_DATABASE2', 'laravel'), 'database' => env('DB_DATABASE2', 'ingest_db'),
'username' => env('DB_USERNAME2', 'root'), 'username' => env('DB_USERNAME2', 'ingest_user'),
'password' => env('DB_PASSWORD2', ''), 'password' => env('DB_PASSWORD2', 'ingest_pwd'),
'charset' => env('DB_CHARSET', 'utf8'), 'charset' => env('DB_CHARSET', 'utf8'),
'prefix' => '', 'prefix' => '',
'prefix_indexes' => true, 'prefix_indexes' => true,
docker-compose.gitea-runner.yml
+74
View File
@@ -0,0 +1,74 @@
version: "3.9"
# Gitea Runner für automatische CI/CD Deployments
# Dieses Compose-File wird auf der Synology NAS deployed
services:
gitea-runner:
image: gitea/act_runner:latest
container_name: gitea-runner
restart: unless-stopped
environment:
# Gitea Instance URL - Passe dies an deine Gitea-Installation an
- GITEA_INSTANCE_URL=${GITEA_URL:-http://gitea:3000}
# Runner Registration Token - Wird aus Gitea UI generiert
- GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
# Runner Name - Wird in Gitea angezeigt
- GITEA_RUNNER_NAME=${RUNNER_NAME:-synology-runner}
# Runner Labels - Definiert welche Workflows dieser Runner ausführen kann
# Format: label:docker://image
- GITEA_RUNNER_LABELS=ubuntu-latest:docker://catthehacker/ubuntu:act-latest,ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04,ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04
# Runner Capacity - Maximale Anzahl gleichzeitiger Jobs
- GITEA_RUNNER_CAPACITY=${RUNNER_CAPACITY:-1}
# Log Level
- GITEA_RUNNER_LOG_LEVEL=${LOG_LEVEL:-info}
volumes:
# Runner Daten (Config, Cache, etc.)
- runner-data:/data
# Docker Socket - Ermöglicht dem Runner Docker-Container zu starten
- /var/run/docker.sock:/var/run/docker.sock
# Optional: Workspace für Job-Artefakte
- runner-workspace:/workspace
networks:
- gitea-network
# Health Check
healthcheck:
test: ["CMD", "pgrep", "-f", "act_runner"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
# Resource Limits (optional, aber empfohlen)
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '1'
memory: 512M
volumes:
runner-data:
driver: local
runner-workspace:
driver: local
networks:
gitea-network:
# Wenn Gitea in einem separaten Netzwerk läuft, verwende:
# external: true
# Ansonsten:
driver: bridge
docker-compose.synology.yml
+91
View File
@@ -0,0 +1,91 @@
version: "3.9"
services:
app:
build:
context: .
dockerfile: Dockerfile
image: laravel-app:latest
container_name: laravel_app
restart: unless-stopped
ports:
- "8080:80" # Angepasst für Synology (Port 81 oft belegt)
environment:
# Laravel Environment
- APP_NAME=${APP_NAME:-Laravel}
- APP_ENV=${APP_ENV:-production}
- APP_KEY=${APP_KEY}
- APP_DEBUG=${APP_DEBUG:-false}
- APP_URL=${APP_URL:-http://localhost:8080}
# Database - PostgreSQL
- DB_CONNECTION2=${DB_CONNECTION2:-pgsql}
- DB_HOST2=${DB_HOST2:-postgres}
- DB_PORT2=${DB_PORT2:-5432}
- DB_DATABASE2=${DB_DATABASE2:-ingest_db}
- DB_USERNAME2=${DB_USERNAME2:-ingest_user}
- DB_PASSWORD2=${DB_PASSWORD2:-ingest_pwd}
# Session & Cache
- SESSION_DRIVER=${SESSION_DRIVER:-file}
- CACHE_STORE=${CACHE_STORE:-file}
- QUEUE_CONNECTION=${QUEUE_CONNECTION:-sync}
# Logging
- LOG_CHANNEL=${LOG_CHANNEL:-stack}
- LOG_LEVEL=${LOG_LEVEL:-info}
# Mail
- MAIL_MAILER=${MAIL_MAILER:-log}
volumes:
- app-storage:/var/www/html/storage
- app-bootstrap-cache:/var/www/html/bootstrap/cache
- ./database:/var/www/html/database
networks:
- laravel-network
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
container_name: laravel_postgres
restart: unless-stopped
environment:
- POSTGRES_DB=${DB_DATABASE2:-ingest_db}
- POSTGRES_USER=${DB_USERNAME2:-ingest_user}
- POSTGRES_PASSWORD=${DB_PASSWORD2:-ingest_pwd}
- PGDATA=/var/lib/postgresql/data/pgdata
volumes:
- postgres-data:/var/lib/postgresql/data
ports:
- "5432:5432" # Optional: Direktzugriff auf PostgreSQL
networks:
- laravel-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME2:-ingest_user}"]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres-data:
driver: local
app-storage:
driver: local
app-bootstrap-cache:
driver: local
networks:
laravel-network:
driver: bridge
docs/api-documentation.md
+999
View File
@@ -0,0 +1,999 @@
# API-Dokumentation: Risk Intelligence Platform
## 📋 Inhaltsverzeichnis
1. [Übersicht](#übersicht)
2. [API-Spezifikation](#api-spezifikation)
3. [Authentication](#authentication)
4. [Endpoints](#endpoints)
5. [Datenmodelle](#datenmodelle)
6. [Beispiele](#beispiele)
7. [Error Handling](#error-handling)
8. [Rate Limiting](#rate-limiting)
9. [Changelog](#changelog)
---
## Übersicht
Die **Trusted AI Analyst Data API** stellt Daten für das Analyst Dashboard, Transaction Review, Company Search und Company Drill-Down bereit.
### API-Version
**Version:** 1.0.0
**Format:** JSON
**Authentifizierung:** Session-basiert (Laravel Session Cookie)
### Base URLs
| Environment | URL |
|-------------|-----|
| **Development** | `http://trusted_ai.test/api` |
| **Production** | `https://afc.trai.sft.comstack.de/api` |
### OpenAPI Spezifikation
Die vollständige API-Spezifikation ist in [swagger.yaml](../swagger.yaml) dokumentiert.
**Swagger UI:** Die Spezifikation kann mit [Swagger Editor](https://editor.swagger.io) oder Swagger UI visualisiert werden.
---
## API-Spezifikation
### API-Kategorien
| Tag | Beschreibung | Endpoints |
|-----|--------------|-----------|
| **Dashboard** | KPIs und Alert-Übersichten | 1 Endpoint |
| **Transactions** | Portfolio-weite Transaction Review | 2 Endpoints |
| **Companies** | Company Discovery & Drill-Down | 4 Endpoints |
**Gesamt:** 7 API-Endpoints
---
## Authentication
### Session-basierte Authentifizierung
Die API nutzt **Laravel Session Cookies** für die Authentifizierung.
```yaml
securitySchemes:
sessionCookie:
type: apiKey
in: cookie
name: laravel_session
```
### Login-Flow
1. **Login via Web-Interface:**
```http
POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
email=user@example.com&password=secret
```
2. **Session Cookie erhalten:**
```http
HTTP/1.1 302 Found
Set-Cookie: laravel_session=eyJ....; Path=/; HttpOnly; SameSite=lax
```
3. **API-Request mit Cookie:**
```http
GET /api/dashboard/overview HTTP/1.1
Cookie: laravel_session=eyJ....
```
### Authentifizierungs-Fehler
```json
HTTP/1.1 401 Unauthorized
{
"message": "Unauthenticated."
}
```
**Wichtig:** Alle API-Endpoints erfordern eine gültige Session!
---
## Endpoints
### 1. Dashboard
#### GET /dashboard/overview
Liefert aggregierte KPIs und Alert-Übersichten für das Dashboard.
**Request:**
```http
GET /api/dashboard/overview HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"generatedAt": "2025-01-19T07:30:00Z",
"activeAnalysts": 24,
"totalTransactions": 312,
"totalVolume": 98765432.10,
"alertsToday": 56,
"averageAlertsPerAnalyst": 3,
"precisionRate": 84,
"activeAlerts": {
"count": 128,
"highRiskCount": 19
},
"riskSegments": [
{
"label": "Kritisch (≥80)",
"count": 17,
"volume": 8900000.0
},
{
"label": "Hoch (60-79)",
"count": 42,
"volume": 15200000.0
},
{
"label": "Mittel (40-59)",
"count": 89,
"volume": 32100000.0
}
],
"topCompanies": [
{
"companyId": 24,
"companyName": "Allianz SE",
"ticker": "ALV",
"sector": "Insurance",
"alerts": 6,
"alertVolume": 1450000.0,
"avgRiskScore": 82
}
],
"runbooksExecutedToday": 41
}
```
---
### 2. Transactions
#### GET /transactions
Liste alle Transaktionen mit globalen Filtern (Portfolio-weite Transaction Review).
**Query Parameters:**
| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `search` | string | - | Match gegen Reference, Counterparty, Company |
| `status` | enum | `all` | `all`, `true_positive`, `false_positive`, `cleared` |
| `page` | integer | `1` | Seiten-Nummer (min: 1) |
| `perPage` | integer | `12` | Items pro Seite (min: 1, max: 100) |
**Request:**
```http
GET /api/transactions?status=true_positive&page=1&perPage=12 HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"filters": {
"statusOptions": [
{
"value": "true_positive",
"label": "Bestätigte Treffer"
},
{
"value": "false_positive",
"label": "Fehlalarme"
},
{
"value": "cleared",
"label": "Freigegeben"
}
],
"perPage": 12
},
"metrics": {
"total": {
"count": 312,
"amount": 98765432.10
},
"byStatus": {
"true_positive": {
"count": 42,
"amount": 15200000.0
},
"false_positive": {
"count": 89,
"amount": 32100000.0
},
"cleared": {
"count": 181,
"amount": 51465432.10
}
}
},
"data": [
{
"id": 512,
"company": {
"id": 12,
"name": "Allianz",
"legalName": "Allianz SE",
"ticker": "ALV",
"sector": "Insurance",
"country": "Germany",
"headquarters": "Munich",
"kycRiskLevel": "high",
"summary": "Multinational insurance provider with EMEA focus."
},
"counterparty": "Alpine Holdings Ltd.",
"counterpartyCountry": "Switzerland",
"status": "true_positive",
"statusLabel": "Bestätigter Treffer",
"requiresReview": true,
"riskScore": 87,
"amount": 245000.75,
"currency": "EUR",
"reference": "PAY-2024-10-1942",
"channel": "SWIFT",
"executedAt": "2025-01-18T09:14:00Z",
"flaggedReason": "Counterparty on sanctions watchlist"
}
],
"pagination": {
"page": 1,
"perPage": 12,
"total": 128,
"lastPage": 11
},
"selectedTransactionId": null,
"selectedTransaction": null
}
```
---
#### GET /transactions/{transactionId}
Hole detaillierte Transaction Case File.
**Path Parameters:**
| Parameter | Typ | Beschreibung |
|-----------|-----|--------------|
| `transactionId` | integer | Transaction ID |
**Request:**
```http
GET /api/transactions/512 HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"id": 512,
"company": { ... },
"counterparty": "Alpine Holdings Ltd.",
"status": "true_positive",
"statusLabel": "Bestätigter Treffer",
"requiresReview": true,
"riskScore": 87,
"amount": 245000.75,
"currency": "EUR",
"reference": "PAY-2024-10-1942",
"channel": "SWIFT",
"executedAt": "2025-01-18T09:14:00Z",
"flaggedBy": "Screening Engine",
"flaggedReason": "Counterparty matched to EU sanctions list",
"signals": [
{
"type": "Adverse Media",
"value": "Enforcement action reported in 2024-11",
"weight": 0.8
},
{
"type": "Sanctions",
"value": "EU Sanctions List Match",
"weight": 1.0
}
]
}
```
**Errors:**
- `401 Unauthorized` - Session ungültig
- `404 Not Found` - Transaction existiert nicht
---
### 3. Companies
#### GET /companies/search
Suche Companies und erhalte Screening-Übersicht.
**Query Parameters:**
| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `q` | string | - | Freitext-Suche (Name, Legal Name, Ticker, Sector) |
| `limit` | integer | `6` | Max. Ergebnisse (min: 1, max: 25) |
**Request:**
```http
GET /api/companies/search?q=Allianz&limit=6 HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"overview": {
"totalCompanies": 40,
"openAlerts": 112,
"openAlertVolume": 5640000.0,
"averageRiskScore": 71,
"watchlistHits": 9,
"automationShare": 82
},
"results": [
{
"id": 12,
"name": "Allianz",
"legalName": "Allianz SE",
"ticker": "ALV",
"sector": "Insurance",
"country": "Germany",
"headquarters": "Munich",
"kycRiskLevel": "high",
"summary": "Multinational insurance provider with EMEA focus.",
"alertCount": 7,
"alertVolume": 980000.0,
"alertRiskScore": 79,
"latestAlert": {
"transactionId": 731,
"counterparty": "Baltic Commodities LLC",
"executedAt": "2025-01-17T11:48:00Z",
"channel": "SWIFT",
"flaggedReason": "Pattern matches sanctions typology",
"riskScore": 88
}
}
],
"meta": {
"query": "Allianz",
"resultCount": 6,
"limit": 6
}
}
```
---
#### GET /companies/{companyId}
Hole Company-Profil.
**Path Parameters:**
| Parameter | Typ | Beschreibung |
|-----------|-----|--------------|
| `companyId` | integer | Company ID |
**Request:**
```http
GET /api/companies/12 HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"id": 12,
"name": "Allianz",
"legalName": "Allianz SE",
"ticker": "ALV",
"sector": "Insurance",
"country": "Germany",
"headquarters": "Munich",
"kycRiskLevel": "high",
"summary": "Multinational insurance provider with EMEA focus.",
"createdAt": "2024-10-15T08:30:00Z",
"updatedAt": "2025-01-18T14:22:00Z"
}
```
**Errors:**
- `401 Unauthorized` - Session ungültig
- `404 Not Found` - Company existiert nicht
---
#### GET /companies/{companyId}/transactions
Liste alle Transactions für eine Company.
**Path Parameters:**
| Parameter | Typ | Beschreibung |
|-----------|-----|--------------|
| `companyId` | integer | Company ID |
**Query Parameters:**
| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `status` | enum | `all` | `all`, `true_positive`, `false_positive`, `cleared` |
| `channel` | string | `all` | Channel-Filter (z.B. `SWIFT`, `SEPA`) |
| `page` | integer | `1` | Seiten-Nummer |
| `perPage` | integer | `10` | Items pro Seite (min: 1, max: 100) |
**Request:**
```http
GET /api/companies/12/transactions?status=true_positive&page=1&perPage=10 HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"company": {
"id": 12,
"name": "Allianz",
"legalName": "Allianz SE",
"ticker": "ALV",
"sector": "Insurance",
"country": "Germany",
"headquarters": "Munich",
"kycRiskLevel": "high",
"summary": "Multinational insurance provider..."
},
"filters": {
"statusOptions": [
{
"value": "true_positive",
"label": "Bestätigte Treffer"
}
],
"channelOptions": [
{
"value": "SWIFT",
"label": "SWIFT"
},
{
"value": "SEPA",
"label": "SEPA"
}
]
},
"metrics": {
"totalCount": 96,
"totalVolume": 7200000.0,
"openAlerts": {
"count": 12,
"amount": 1850000.0
},
"highRiskShare": 28,
"last30Days": {
"count": 15,
"amount": 980000.0
},
"byStatus": {
"true_positive": {
"count": 12,
"amount": 1850000.0
},
"false_positive": {
"count": 24,
"amount": 2100000.0
},
"cleared": {
"count": 60,
"amount": 3250000.0
}
}
},
"data": [
{
"id": 877,
"company": { ... },
"counterparty": "Alpine Holdings Ltd.",
"status": "true_positive",
"riskScore": 87,
"amount": 245000.75,
"currency": "EUR",
"reference": "PAY-2024-10-1942",
"channel": "SWIFT",
"executedAt": "2025-01-18T09:14:00Z"
}
],
"pagination": {
"page": 1,
"perPage": 10,
"total": 12,
"lastPage": 2
},
"selectedTransactionId": null,
"selectedTransaction": null,
"recentAlerts": [
{
"id": 911,
"counterparty": "Northbridge Trading Ltd.",
"executedAt": "2025-01-18T14:52:00Z",
"channel": "SWIFT",
"status": "true_positive",
"statusLabel": "Bestätigter Treffer",
"riskScore": 92
}
]
}
```
**Errors:**
- `401 Unauthorized` - Session ungültig
- `404 Not Found` - Company nicht gefunden oder keine Transactions
---
#### GET /companies/{companyId}/transactions/{transactionId}
Hole Transaction Case File mit Company-Context und History.
**Path Parameters:**
| Parameter | Typ | Beschreibung |
|-----------|-----|--------------|
| `companyId` | integer | Company ID |
| `transactionId` | integer | Transaction ID |
**Request:**
```http
GET /api/companies/12/transactions/877 HTTP/1.1
Cookie: laravel_session=...
```
**Response:** `200 OK`
```json
{
"id": 877,
"company": { ... },
"counterparty": "Alpine Holdings Ltd.",
"status": "true_positive",
"statusLabel": "Bestätigter Treffer",
"requiresReview": true,
"riskScore": 87,
"amount": 245000.75,
"currency": "EUR",
"reference": "PAY-2024-10-1942",
"channel": "SWIFT",
"executedAt": "2025-01-18T09:14:00Z",
"flaggedBy": "Screening Engine",
"flaggedReason": "Counterparty matched to EU sanctions list",
"signals": [
{
"type": "Adverse Media",
"value": "Enforcement action reported in 2024-11",
"weight": 0.8
}
],
"recommendedActions": [
{
"title": "Verdachtsmeldung vorbereiten",
"description": "Erstellen Sie den Meldeentwurf für die FIU und sichern Sie Belege."
},
{
"title": "Enhanced Due Diligence",
"description": "Prüfen Sie zusätzliche Informationsquellen zur Counterparty."
}
],
"counterpartyHistory": [
{
"id": 765,
"executedAt": "2024-12-22T15:37:00Z",
"channel": "SWIFT",
"reference": "PAY-2024-12-1187",
"amount": 99000.0,
"currency": "EUR",
"riskScore": 74
}
]
}
```
**Errors:**
- `401 Unauthorized` - Session ungültig
- `404 Not Found` - Transaction nicht gefunden für diese Company
---
## Datenmodelle
### Transaction Status
```typescript
enum TransactionStatus {
TRUE_POSITIVE = 'true_positive', // Kritisches Risiko
FALSE_POSITIVE = 'false_positive', // Hohes Risiko
CLEARED = 'cleared' // Geringes Risiko
}
```
### KYC Risk Level
```typescript
enum KycRiskLevel {
LOW = 'low',
HIGH = 'high',
CRITICAL = 'critical'
}
```
### Pagination Meta
```json
{
"page": 1,
"perPage": 12,
"total": 128,
"lastPage": 11
}
```
### Count Amount Summary
```json
{
"count": 42,
"amount": 2750000.50
}
```
### Transaction Signal
```json
{
"type": "Adverse Media",
"value": "Enforcement action reported in 2024-11",
"weight": 0.8
}
```
### Recommended Action
```json
{
"title": "Verdachtsmeldung vorbereiten",
"description": "Erstellen Sie den Meldeentwurf für die FIU..."
}
```
---
## Beispiele
### cURL-Beispiele
#### Login & Session Cookie erhalten
```bash
# Login
curl -c cookies.txt -X POST http://trusted_ai.test/login \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "email=user@example.com&password=secret"
# Session Cookie ist jetzt in cookies.txt gespeichert
```
#### Dashboard Overview abrufen
```bash
curl -b cookies.txt http://trusted_ai.test/api/dashboard/overview
```
#### Transactions filtern
```bash
curl -b cookies.txt "http://trusted_ai.test/api/transactions?status=true_positive&page=1&perPage=12"
```
#### Company suchen
```bash
curl -b cookies.txt "http://trusted_ai.test/api/companies/search?q=Allianz&limit=6"
```
#### Company Transactions abrufen
```bash
curl -b cookies.txt "http://trusted_ai.test/api/companies/12/transactions?status=all&page=1"
```
---
### JavaScript (Fetch API)
```javascript
// Session Cookie wird automatisch vom Browser gesendet
// Dashboard Overview
const overview = await fetch('/api/dashboard/overview', {
credentials: 'include' // Wichtig: Session Cookie mitsenden
}).then(r => r.json());
console.log(overview);
// Transactions mit Filter
const transactions = await fetch('/api/transactions?status=true_positive&page=1&perPage=12', {
credentials: 'include'
}).then(r => r.json());
console.log(transactions.data);
// Company Search
const companies = await fetch('/api/companies/search?q=Allianz', {
credentials: 'include'
}).then(r => r.json());
console.log(companies.results);
```
---
### TypeScript Types
```typescript
// Dashboard Overview Response
interface DashboardOverview {
generatedAt: string;
activeAnalysts: number;
totalTransactions: number;
totalVolume: number;
alertsToday: number;
averageAlertsPerAnalyst: number;
precisionRate: number;
activeAlerts: {
count: number;
highRiskCount: number;
};
riskSegments: RiskSegment[];
topCompanies: TopCompanyAlert[];
runbooksExecutedToday: number;
}
// Transaction Collection Response
interface TransactionCollectionResponse {
filters: {
statusOptions: StatusOption[];
perPage: number;
};
metrics: TransactionMetrics;
data: TransactionPreview[];
pagination: PaginationMeta;
selectedTransactionId: number | null;
selectedTransaction: TransactionDetail | null;
}
// Company Search Response
interface CompanySearchResponse {
overview: CompanySearchOverview;
results: CompanySearchResult[];
meta: {
query: string | null;
resultCount: number;
limit: number;
};
}
```
---
## Error Handling
### Standard Error Response
```json
{
"message": "Error message",
"errors": {
"field": ["Validation error"]
}
}
```
### HTTP Status Codes
| Code | Bedeutung | Beschreibung |
|------|-----------|--------------|
| `200` | OK | Request erfolgreich |
| `401` | Unauthorized | Session ungültig oder abgelaufen |
| `404` | Not Found | Resource nicht gefunden |
| `422` | Unprocessable Entity | Validierungsfehler |
| `500` | Internal Server Error | Server-Fehler |
### Beispiel: 401 Unauthorized
```json
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Unauthenticated."
}
```
**Aktion:** Redirect zu `/login`
### Beispiel: 404 Not Found
```json
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "Company not found."
}
```
### Beispiel: 422 Validation Error
```json
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"message": "The given data was invalid.",
"errors": {
"status": ["The selected status is invalid."],
"page": ["The page must be at least 1."]
}
}
```
---
## Rate Limiting
### Aktueller Status
**Aktuell:** Kein Rate Limiting implementiert.
### Geplant (Future)
```
Rate Limit: 60 Requests pro Minute pro User
Header: X-RateLimit-Limit, X-RateLimit-Remaining
```
**Response bei Überschreitung:**
```json
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
{
"message": "Too many requests. Please try again later."
}
```
---
## Changelog
### Version 1.0.0 (2025-01-19)
**Initial Release**
**Endpoints:**
- ✅ `GET /dashboard/overview` - Dashboard KPIs
- ✅ `GET /transactions` - Portfolio-wide Transactions
- ✅ `GET /transactions/{id}` - Transaction Detail
- ✅ `GET /companies/search` - Company Search
- ✅ `GET /companies/{id}` - Company Profile
- ✅ `GET /companies/{id}/transactions` - Company Transactions
- ✅ `GET /companies/{id}/transactions/{id}` - Company Transaction Detail
**Features:**
- Session-basierte Authentifizierung
- Pagination Support
- Filter & Search
- Metrics & Aggregationen
- OpenAPI 3.1 Spezifikation
---
## Implementierungs-Status
### ⚠️ Wichtig: API noch nicht implementiert!
Die in diesem Dokument beschriebenen Endpoints sind **aktuell noch nicht implementiert**.
**Status:**
- ✅ OpenAPI Spezifikation vorhanden ([swagger.yaml](../swagger.yaml))
- ❌ API Routes noch nicht definiert (`routes/api.php` ist leer)
- ❌ API Controllers noch nicht erstellt
- ❌ API Responses noch nicht implementiert
### Nächste Schritte zur Implementierung
1. **API Routes definieren:**
```php
// routes/api.php
Route::middleware(['auth:sanctum'])->group(function () {
Route::get('/dashboard/overview', [DashboardController::class, 'overview']);
Route::get('/transactions', [TransactionController::class, 'index']);
Route::get('/transactions/{transaction}', [TransactionController::class, 'show']);
Route::get('/companies/search', [CompanyController::class, 'search']);
Route::get('/companies/{company}', [CompanyController::class, 'show']);
Route::get('/companies/{company}/transactions', [CompanyController::class, 'transactions']);
});
```
2. **API Controllers erstellen:**
```bash
php artisan make:controller Api/DashboardController
php artisan make:controller Api/TransactionController
php artisan make:controller Api/CompanyController
```
3. **API Resources erstellen:**
```bash
php artisan make:resource TransactionResource
php artisan make:resource CompanyResource
```
4. **Tests schreiben:**
```bash
php artisan make:test Api/DashboardTest
php artisan make:test Api/TransactionTest
php artisan make:test Api/CompanyTest
```
---
## Zusammenfassung
### API-Übersicht
| Kategorie | Endpoints | Status |
|-----------|-----------|--------|
| Dashboard | 1 | ⚠️ Spezifiziert, nicht implementiert |
| Transactions | 2 | ⚠️ Spezifiziert, nicht implementiert |
| Companies | 4 | ⚠️ Spezifiziert, nicht implementiert |
| **Gesamt** | **7** | - |
### Datenmodelle
- **DashboardOverview** - Dashboard-KPIs
- **TransactionCollectionResponse** - Paginierte Transactions
- **TransactionDetail** - Detaillierte Transaction
- **CompanySearchResponse** - Company-Suchergebnisse
- **CompanyDetail** - Company-Profil
- **CompanyTransactionsResponse** - Company-spezifische Transactions
### Authentifizierung
**Session-basiert** via Laravel Session Cookie
- Login erforderlich
- Cookie-basierte Authentifizierung
- CSRF-Protection
---
**Erstellt:** 2025-11-24
**Version:** 1.0.0
**Autor:** Risk Intelligence Platform Team
**OpenAPI Spec:** [swagger.yaml](../swagger.yaml)
docs/architecture-overview.md
+1010
View File
File diff suppressed because it is too large. Load diff
docs/data-model-documentation.md
+1153
View File
File diff suppressed because it is too large. Load diff
docs/deployment-guide.md
+1035
View File
File diff suppressed because it is too large. Load diff
docs/developer-setup-guide.md
+991
View File
@@ -0,0 +1,991 @@
# Entwickler-Setup-Guide: Risk Intelligence Platform
## 📋 Inhaltsverzeichnis
1. [Voraussetzungen](#voraussetzungen)
2. [Schnellstart](#schnellstart)
3. [Detaillierte Installation](#detaillierte-installation)
4. [Datenbank-Setup](#datenbank-setup)
5. [Environment-Konfiguration](#environment-konfiguration)
6. [Frontend-Assets](#frontend-assets)
7. [Erste Schritte](#erste-schritte)
8. [Development-Workflow](#development-workflow)
9. [Troubleshooting](#troubleshooting)
10. [Nützliche Commands](#nützliche-commands)
---
## Voraussetzungen
### Erforderliche Software
| Software | Mindestversion | Empfohlen | Installation |
|----------|---------------|-----------|--------------|
| **PHP** | 8.2 | 8.4.14+ | [Laravel Herd](https://herd.laravel.com) |
| **Composer** | 2.0 | Latest | Via Herd oder [getcomposer.org](https://getcomposer.org) |
| **Node.js** | 18.x | 20.x+ | [nodejs.org](https://nodejs.org) |
| **npm** | 9.x | Latest | Mit Node.js installiert |
| **PostgreSQL** | 14.x | 16.x+ | [postgresql.org](https://www.postgresql.org) |
| **Git** | 2.x | Latest | [git-scm.com](https://git-scm.com) |
### Empfohlene Tools
- **Laravel Herd** - Lokale PHP-Entwicklungsumgebung (macOS)
- **TablePlus** / **pgAdmin** - PostgreSQL GUI
- **VS Code** - Editor mit PHP/Laravel Extensions
- **Postman** / **Insomnia** - API Testing (optional)
### PHP Extensions
Folgende PHP Extensions werden benötigt:
```bash
# Prüfe installierte Extensions
php -m
# Benötigte Extensions:
- pdo_pgsql # PostgreSQL Driver
- mbstring # Multibyte String
- xml # XML Support
- curl # HTTP Client
- bcmath # Precision Math
- fileinfo # File Information
- json # JSON Support
- openssl # Encryption
- tokenizer # PHP Tokenizer
- zip # ZIP Archive
```
---
## Schnellstart
Für erfahrene Entwickler - vollständige Installation in 5 Minuten:
```bash
# 1. Repository klonen
git clone <repository-url> risk-platform
cd risk-platform
# 2. Dependencies installieren & Setup ausführen
composer setup
# 3. PostgreSQL-Datenbank erstellen (siehe unten)
# Anpassen: .env mit DB-Credentials
# 4. Migrations ausführen
php artisan migrate --seed
# 5. Development-Server starten
composer run dev
```
**Fertig!** Die Applikation läuft auf [http://localhost:8000](http://localhost:8000)
---
## Detaillierte Installation
### Schritt 1: Repository klonen
```bash
# Via HTTPS
git clone https://github.com/your-org/risk-platform.git
cd risk-platform
# Oder via SSH
git clone git@github.com:your-org/risk-platform.git
cd risk-platform
```
### Schritt 2: PHP Dependencies installieren
```bash
composer install
```
**Was passiert dabei?**
- Installiert alle Laravel-Pakete
- Installiert Livewire, Flux UI, Fortify
- Installiert Dev-Dependencies (Pest, Pint, Boost)
- Generiert Autoload-Files
### Schritt 3: Environment-Datei erstellen
```bash
# .env.example nach .env kopieren
cp .env.example .env
# Application Key generieren
php artisan key:generate
```
### Schritt 4: Node Dependencies installieren
```bash
npm install
```
**Was passiert dabei?**
- Installiert Vite
- Installiert Tailwind CSS v4
- Installiert Build-Tools
---
## Datenbank-Setup
### PostgreSQL Installation
#### macOS (mit Homebrew)
```bash
# PostgreSQL installieren
brew install postgresql@16
# Als Service starten
brew services start postgresql@16
# Verbindung testen
psql postgres
```
#### macOS (mit Postgres.app)
1. Download von [postgresapp.com](https://postgresapp.com)
2. App starten
3. Default Server initialisieren
#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
```
### Datenbank erstellen
```bash
# Als postgres User einloggen
psql postgres
# Oder direkt mit spezifischem User
sudo -u postgres psql
```
```sql
-- Datenbank erstellen
CREATE DATABASE risk_platform_db;
-- User erstellen (optional)
CREATE USER risk_user WITH ENCRYPTED PASSWORD 'your_secure_password';
-- Rechte vergeben
GRANT ALL PRIVILEGES ON DATABASE risk_platform_db TO risk_user;
-- In PostgreSQL 15+ auch Schema-Rechte vergeben
\c risk_platform_db
GRANT ALL ON SCHEMA public TO risk_user;
-- Exit
\q
```
### Schemas erstellen
```sql
-- Verbindung zur DB
psql -U risk_user -d risk_platform_db
-- PUBLIC Schema (wird automatisch erstellt)
-- BACKEND Schema erstellen
CREATE SCHEMA IF NOT EXISTS backend;
-- Rechte für BACKEND Schema
GRANT ALL ON SCHEMA backend TO risk_user;
-- Exit
\q
```
### Verbindung testen
```bash
# Direkter Connect
psql -h 127.0.0.1 -p 5432 -U risk_user -d risk_platform_db
# Mit Laravel Tinker
php artisan tinker
>>> DB::connection('pgsql_second')->select('SELECT version()');
>>> DB::connection('backend')->select('SELECT current_schema()');
```
---
## Environment-Konfiguration
### .env Datei anpassen
```bash
# .env öffnen und anpassen
nano .env
```
#### Grundkonfiguration
```ini
APP_NAME="Risk Intelligence Platform"
APP_ENV=local
APP_KEY=base64:xxx # Wird von key:generate erstellt
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_LOCALE=de
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=de_DE
```
#### Datenbank-Konfiguration (Wichtig!)
```ini
# Default Connection (PUBLIC Schema)
DB_CONNECTION=pgsql
DB_CONNECTION2=pgsql
DB_HOST2=127.0.0.1
DB_PORT2=5432
DB_DATABASE2=risk_platform_db
DB_USERNAME2=risk_user
DB_PASSWORD2=your_secure_password
```
**Wichtig:** Die Applikation nutzt `DB_*2` Variablen für PostgreSQL!
#### Cache & Session
```ini
CACHE_STORE=database
SESSION_DRIVER=database
QUEUE_CONNECTION=database
```
**Warum database?**
- Einfaches Setup ohne Redis
- Funktioniert out-of-the-box
- Für Produktion: Wechsel zu Redis empfohlen
#### Mail-Konfiguration (Development)
```ini
MAIL_MAILER=log
MAIL_FROM_ADDRESS="noreply@risk-platform.test"
MAIL_FROM_NAME="${APP_NAME}"
```
Mails werden in `storage/logs/laravel.log` gespeichert.
#### Optional: Redis (für bessere Performance)
```ini
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
```
### Vollständige .env Vorlage
<details>
<summary>Klicken für vollständige .env Beispiel-Datei</summary>
```ini
APP_NAME="Risk Intelligence Platform"
APP_ENV=local
APP_KEY=base64:xxx
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_LOCALE=de
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=de_DE
APP_MAINTENANCE_DRIVER=file
PHP_CLI_SERVER_WORKERS=4
BCRYPT_ROUNDS=12
LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug
# PostgreSQL Configuration
DB_CONNECTION=pgsql
DB_CONNECTION2=pgsql
DB_HOST2=127.0.0.1
DB_PORT2=5432
DB_DATABASE2=risk_platform_db
DB_USERNAME2=risk_user
DB_PASSWORD2=your_secure_password
# Session & Cache
SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null
CACHE_STORE=database
QUEUE_CONNECTION=database
# Broadcasting & Filesystem
BROADCAST_CONNECTION=log
FILESYSTEM_DISK=local
# Mail
MAIL_MAILER=log
MAIL_FROM_ADDRESS="noreply@risk-platform.test"
MAIL_FROM_NAME="${APP_NAME}"
# Vite
VITE_APP_NAME="${APP_NAME}"
```
</details>
---
## Frontend-Assets
### Assets kompilieren
```bash
# Development Build (einmalig)
npm run build
# Development mit Hot Reload
npm run dev
```
### Was macht `npm run dev`?
```
┌─────────────────────────────────────────────────┐
│ VITE v7.0.4 ready in X ms │
│ │
│ ➜ Local: http://localhost:5173/ │
│ ➜ Network: use --host to expose │
│ │
│ ➜ Laravel: http://localhost:8000 │
└─────────────────────────────────────────────────┘
✓ compiled successfully
```
- Startet Vite Dev-Server auf Port 5173
- Hot Module Replacement (HMR) aktiviert
- Tailwind CSS v4 wird kompiliert
- Livewire-Assets werden gebundled
### Production Build
```bash
npm run build
# Output:
# dist/assets/app-xxxxx.js
# dist/assets/app-xxxxx.css
```
---
## Erste Schritte
### 1. Migrations ausführen
```bash
# Alle Migrations ausführen
php artisan migrate
# Mit Seeding (Test-Daten)
php artisan migrate --seed
# Migration-Status prüfen
php artisan migrate:status
```
**Erwartete Tabellen nach Migration:**
```
┌──────────────────────────────────┬────────┐
│ Migration │ Ran? │
├──────────────────────────────────┼────────┤
│ 0001_01_01_000000_create_users │ Yes │
│ 0001_01_01_000001_create_cache │ Yes │
│ 0001_01_01_000002_create_jobs │ Yes │
│ 2025_09_02_075243_add_two_factor │ Yes │
│ 2025_10_20_181750_create_companies │ Yes │
│ 2025_10_20_181753_create_transactions │ Yes │
│ 2025_11_16_140224_add_output_columns │ Yes │
│ 2025_11_16_150000_create_backend_data_pool │ Yes │
│ ... │ │
└──────────────────────────────────┴────────┘
```
### 2. Test-User erstellen
```bash
php artisan tinker
```
```php
// Test-User erstellen
$user = App\Models\User::create([
'name' => 'Admin User',
'email' => 'admin@example.com',
'password' => bcrypt('password'),
'email_verified_at' => now(),
]);
// Oder mit Factory
App\Models\User::factory()->create([
'email' => 'test@example.com',
]);
exit
```
### 3. Development-Server starten
#### Option A: Composer Dev Command (Empfohlen)
```bash
composer run dev
```
**Startet parallel:**
- `php artisan serve` → http://localhost:8000
- `php artisan queue:listen` → Queue Worker
- `php artisan pail` → Live Logs
- `npm run dev` → Vite Dev Server
#### Option B: Einzelne Services manuell
```bash
# Terminal 1: Laravel Server
php artisan serve
# Terminal 2: Vite Dev Server
npm run dev
# Terminal 3 (optional): Queue Worker
php artisan queue:work
# Terminal 4 (optional): Logs
php artisan pail
```
#### Option C: Laravel Herd (macOS)
Wenn du Laravel Herd nutzt:
1. Projekt in Herd-Verzeichnis verschieben
2. Automatische Domain: `risk-platform.test`
3. HTTPS automatisch aktiviert
4. Kein `php artisan serve` notwendig
```bash
# In Herd-Verzeichnis verschieben
mv ~/risk-platform ~/Herd/risk-platform
# Browser öffnen
open https://risk-platform.test
```
### 4. Applikation öffnen
Browser öffnen: [http://localhost:8000](http://localhost:8000)
**Login-Credentials:**
- Email: `test@example.com`
- Password: `password`
---
## Development-Workflow
### Typischer Entwicklungstag
```bash
# 1. Morgen: Repository aktualisieren
git pull origin main
# 2. Dependencies aktualisieren (falls composer.lock geändert)
composer install
npm install
# 3. Neue Migrations (falls vorhanden)
php artisan migrate
# 4. Dev-Server starten
composer run dev
# 5. Am Ende: Code formatieren
vendor/bin/pint
# 6. Tests ausführen
php artisan test
# 7. Commit & Push
git add .
git commit -m "feat: neue feature"
git push
```
### Code-Formatierung
```bash
# Alle Dateien formatieren
vendor/bin/pint
# Nur geänderte Dateien
vendor/bin/pint --dirty
# Test-Modus (ohne Änderungen)
vendor/bin/pint --test
```
### Tests ausführen
```bash
# Alle Tests
php artisan test
# Nur Feature Tests
php artisan test --testsuite=Feature
# Nur Unit Tests
php artisan test --testsuite=Unit
# Spezifische Test-Datei
php artisan test tests/Feature/CompanyTest.php
# Mit Filter
php artisan test --filter=testCompanyCreation
# Mit Coverage (benötigt Xdebug)
php artisan test --coverage
```
### Backend-Daten synchronisieren
```bash
# Stats anzeigen (kein Sync)
php artisan backend:sync-data-pool --stats
# Incremental Sync
php artisan backend:sync-data-pool --incremental
# Full Sync
php artisan backend:sync-data-pool --full
# Transformation
php artisan backend:transform-data-pool
# Kompletter Rebuild
php artisan backend:rebuild
```
### Scheduler lokal testen
```bash
# Schedule Worker (läuft dauerhaft)
php artisan schedule:work
# Oder: Nächste Due-Tasks anzeigen
php artisan schedule:list
# Einzelnen Task testen
php artisan schedule:test sync-backend-data-pool-incremental
```
---
## Troubleshooting
### Problem: "SQLSTATE[08006] Connection refused"
**Ursache:** PostgreSQL läuft nicht oder falsche Credentials
**Lösung:**
```bash
# PostgreSQL-Status prüfen
brew services list | grep postgresql
# PostgreSQL starten
brew services start postgresql@16
# Verbindung testen
psql -h 127.0.0.1 -p 5432 -U risk_user -d risk_platform_db
# .env prüfen
cat .env | grep DB_
```
---
### Problem: "Class 'PDO' not found"
**Ursache:** PHP PostgreSQL Extension fehlt
**Lösung:**
```bash
# Installierte Extensions prüfen
php -m | grep pdo
# Mit Herd (macOS)
# Extensions sind normalerweise vorinstalliert
# Oder PHP neu installieren via Homebrew
brew reinstall php@8.4
```
---
### Problem: "Vite manifest not found"
**Ursache:** Frontend-Assets nicht kompiliert
**Lösung:**
```bash
# Development Build
npm run build
# Oder Dev-Server starten
npm run dev
```
---
### Problem: "419 Page Expired" bei Forms
**Ursache:** CSRF-Token ungültig (Session abgelaufen)
**Lösung:**
```bash
# Cache leeren
php artisan config:clear
php artisan cache:clear
php artisan view:clear
# Browser: Hard Refresh (Cmd+Shift+R / Ctrl+Shift+R)
```
---
### Problem: Migrations laufen nicht
**Ursache:** Datenbank-Schema fehlt oder keine Rechte
**Lösung:**
```bash
# Schema-Rechte prüfen
psql -U risk_user -d risk_platform_db
# In psql:
SELECT schema_name FROM information_schema.schemata;
# Rechte vergeben
GRANT ALL ON SCHEMA public TO risk_user;
GRANT ALL ON ALL TABLES IN SCHEMA public TO risk_user;
# Migration erneut versuchen
php artisan migrate
```
---
### Problem: Queue-Jobs laufen nicht
**Ursache:** Queue-Worker läuft nicht
**Lösung:**
```bash
# Queue-Worker starten
php artisan queue:work
# Oder mit Auto-Restart bei Code-Änderungen
php artisan queue:listen
# Failed Jobs anzeigen
php artisan queue:failed
# Failed Jobs erneut versuchen
php artisan queue:retry all
```
---
### Problem: "Class not found" Fehler
**Ursache:** Autoload-Cache veraltet
**Lösung:**
```bash
# Autoload neu generieren
composer dump-autoload
# Alle Caches leeren
php artisan optimize:clear
# Oder einzeln:
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
```
---
### Problem: Livewire-Components laden nicht
**Ursache:** Volt-Components nicht registriert
**Lösung:**
```bash
# Volt Provider prüfen
cat bootstrap/providers.php | grep Volt
# Cache leeren
php artisan optimize:clear
# Browser Cache leeren
# Cmd+Shift+R (macOS) oder Ctrl+Shift+R (Windows/Linux)
```
---
### Problem: Styling fehlt / Tailwind funktioniert nicht
**Ursache:** Vite-Server läuft nicht oder falsche Konfiguration
**Lösung:**
```bash
# Vite Dev-Server neu starten
npm run dev
# Oder Production-Build
npm run build
# Tailwind-Config prüfen
cat tailwind.config.js
# Node-Modules neu installieren
rm -rf node_modules package-lock.json
npm install
```
---
## Nützliche Commands
### Laravel Artisan
```bash
# Liste aller Commands
php artisan list
# Command-Hilfe
php artisan help migrate
# Interaktive Shell
php artisan tinker
# Cache Management
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan optimize:clear # Alle Caches auf einmal
# Database
php artisan db:show # DB-Info anzeigen
php artisan migrate:status # Migration-Status
php artisan migrate:fresh --seed # DB neu aufsetzen + Seeds
# Make Commands
php artisan make:model Company
php artisan make:controller CompanyController
php artisan make:migration create_companies_table
php artisan make:livewire CompanySearch
php artisan make:test CompanyTest
php artisan make:class Services/MyService
# Routes
php artisan route:list # Alle Routes anzeigen
php artisan route:list --path=companies # Gefiltert
```
### Composer
```bash
# Dependencies installieren
composer install
# Development-Dependencies überspringen
composer install --no-dev
# Einzelnes Package installieren
composer require laravel/telescope
# Package entfernen
composer remove laravel/telescope
# Autoload regenerieren
composer dump-autoload
# Setup ausführen (custom script)
composer setup
# Dev-Server starten (custom script)
composer run dev
# Tests ausführen (custom script)
composer test
```
### NPM
```bash
# Dependencies installieren
npm install
# Dev-Server starten
npm run dev
# Production Build
npm run build
# Package installieren
npm install alpine.js
# Package entfernen
npm uninstall alpine.js
# Outdated Packages prüfen
npm outdated
# Updates installieren
npm update
```
### Git
```bash
# Aktueller Branch
git branch
# Neuen Branch erstellen
git checkout -b feature/neue-funktion
# Änderungen anzeigen
git status
git diff
# Commit
git add .
git commit -m "feat: neue funktion"
git push origin feature/neue-funktion
# Main aktualisieren
git checkout main
git pull origin main
```
### PostgreSQL
```bash
# Verbinden
psql -U risk_user -d risk_platform_db
# In psql:
\dt # Alle Tabellen
\d companies # Tabellen-Schema anzeigen
\dn # Alle Schemas
\du # Alle User
\l # Alle Datenbanken
\q # Exit
# Backup erstellen
pg_dump -U risk_user risk_platform_db > backup.sql
# Backup einspielen
psql -U risk_user risk_platform_db < backup.sql
```
---
## Nächste Schritte
Nach erfolgreichem Setup:
1. **Architektur-Dokumentation lesen** → [docs/architecture-overview.md](architecture-overview.md)
2. **Backend-Sync Commands kennenlernen** → [docs/backend-sync-commands.md](backend-sync-commands.md)
3. **Code-Konventionen studieren** → [CLAUDE.md](../CLAUDE.md)
4. **Tests schreiben & ausführen** → `php artisan test`
5. **Erste Änderungen committen** → `git commit`
---
## Hilfe & Support
### Dokumentation
- **Architektur-Übersicht:** [docs/architecture-overview.md](architecture-overview.md)
- **Backend-Sync:** [docs/backend-sync-commands.md](backend-sync-commands.md)
- **Scheduling:** [docs/scheduling-setup.md](scheduling-setup.md)
- **Migration:** [docs/sync-migration-instructions.md](sync-migration-instructions.md)
### Laravel Dokumentation
- **Laravel 12:** [https://laravel.com/docs/12.x](https://laravel.com/docs/12.x)
- **Livewire 3:** [https://livewire.laravel.com](https://livewire.laravel.com)
- **Flux UI:** [https://flux.laravel.com](https://flux.laravel.com)
- **Pest Testing:** [https://pestphp.com](https://pestphp.com)
### Logs prüfen
```bash
# Application Logs (Live)
tail -f storage/logs/laravel.log
# Nur Fehler
tail -f storage/logs/laravel.log | grep ERROR
# Mit Laravel Pail (farbig)
php artisan pail
```
### Debugging
```bash
# Laravel Debugbar (installiert)
# Aktiviert automatisch wenn APP_DEBUG=true
# Erscheint am unteren Bildschirmrand im Browser
# Tinker für schnelle Tests
php artisan tinker
>>> App\Models\Company::count()
>>> DB::table('transactions')->latest()->first()
```
---
**Setup-Zeit:** ~15-30 Minuten
**Erstellt:** 2025-11-24
**Version:** 1.0
**Autor:** Risk Intelligence Platform Team
Viel Erfolg beim Entwickeln! 🚀
docs/testing-guide.md
+1047
View File
File diff suppressed because it is too large. Load diff
routes/web.php
+9
View File
@@ -8,6 +8,15 @@ Route::get('/', function () {
return view('welcome'); return view('welcome');
})->name('home'); })->name('home');
Route::get('/health', function () {
return response()->json([
'status' => 'healthy',
'timestamp' => now()->toIso8601String(),
'app' => config('app.name'),
'env' => config('app.env'),
]);
})->name('health');
Route::view('dashboard', 'dashboard') Route::view('dashboard', 'dashboard')
->middleware(['auth', 'verified']) ->middleware(['auth', 'verified'])
->name('dashboard'); ->name('dashboard');
scripts/deploy-synology.sh
Executable
+258
View File
@@ -0,0 +1,258 @@
#!/bin/bash
# Deployment Script für Synology NAS
# Dieses Script wird auf der Synology NAS ausgeführt
set -e # Exit on error
# ============================================
# Configuration
# ============================================
PROJECT_DIR="/volume1/docker/laravel-app"
DOCKER_IMAGE="laravel-app"
COMPOSE_FILE="docker-compose.synology.yml"
ENV_FILE=".env.synology"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# ============================================
# Helper Functions
# ============================================
log_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}
log_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# ============================================
# Pre-deployment Checks
# ============================================
log_info "Starting deployment process..."
# Check if running on Synology
if [ ! -d "/volume1" ]; then
log_error "This script should be run on Synology NAS"
exit 1
fi
# Navigate to project directory
cd "$PROJECT_DIR" || {
log_error "Project directory not found: $PROJECT_DIR"
exit 1
}
# Check if Docker is installed
if ! command -v docker &> /dev/null; then
log_error "Docker is not installed"
exit 1
fi
# Check if docker-compose is installed
if ! command -v docker-compose &> /dev/null; then
log_error "docker-compose is not installed"
exit 1
fi
# ============================================
# Load Docker Image
# ============================================
if [ -f "laravel-app.tar.gz" ]; then
log_info "Loading Docker image from artifact..."
gunzip -c laravel-app.tar.gz | docker load
# Tag the image appropriately
LOADED_IMAGE=$(docker images --format "{{.Repository}}:{{.Tag}}" | grep laravel-app | head -n1)
if [ -n "$LOADED_IMAGE" ]; then
docker tag "$LOADED_IMAGE" "${DOCKER_IMAGE}:latest"
log_info "Tagged image as ${DOCKER_IMAGE}:latest"
fi
else
log_warn "No Docker image artifact found. Using existing image or building..."
# Check if Dockerfile exists and build if necessary
if [ -f "Dockerfile" ]; then
log_info "Building Docker image..."
docker build -t "${DOCKER_IMAGE}:latest" .
else
log_error "Neither Docker artifact nor Dockerfile found"
exit 1
fi
fi
# ============================================
# Environment Configuration
# ============================================
if [ ! -f "$ENV_FILE" ]; then
log_warn "Environment file not found: $ENV_FILE"
if [ -f ".env.synology.example" ]; then
log_info "Copying from .env.synology.example..."
cp .env.synology.example "$ENV_FILE"
log_warn "⚠️ Please configure $ENV_FILE with your settings!"
else
log_error "No environment configuration found"
exit 1
fi
fi
# ============================================
# Backup Current Deployment
# ============================================
log_info "Creating backup of current deployment..."
BACKUP_DIR="/volume1/docker/backups/laravel-app"
mkdir -p "$BACKUP_DIR"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/backup_${TIMESTAMP}.tar.gz"
# Backup database if container is running
if docker ps --format '{{.Names}}' | grep -q "laravel_postgres"; then
log_info "Backing up PostgreSQL database..."
docker exec laravel_postgres pg_dump -U ingest_user ingest_db > "$BACKUP_DIR/db_${TIMESTAMP}.sql"
fi
# Keep only last 5 backups
log_info "Cleaning old backups (keeping last 5)..."
ls -t "$BACKUP_DIR"/db_*.sql 2>/dev/null | tail -n +6 | xargs -r rm
# ============================================
# Stop Current Containers
# ============================================
log_info "Stopping current containers..."
if [ -f "$COMPOSE_FILE" ]; then
docker-compose -f "$COMPOSE_FILE" down || log_warn "No containers to stop"
else
log_warn "Compose file not found: $COMPOSE_FILE"
fi
# ============================================
# Clean up old images (optional)
# ============================================
log_info "Cleaning up old Docker images..."
docker image prune -f
# ============================================
# Start New Deployment
# ============================================
log_info "Starting new deployment..."
if [ ! -f "$COMPOSE_FILE" ]; then
log_error "Docker Compose file not found: $COMPOSE_FILE"
exit 1
fi
# Pull/use latest images and start services
docker-compose -f "$COMPOSE_FILE" up -d --build
# ============================================
# Wait for Services to Start
# ============================================
log_info "Waiting for services to start..."
sleep 10
# Check if containers are running
if ! docker ps --format '{{.Names}}' | grep -q "laravel_app"; then
log_error "Laravel app container failed to start"
# Show logs
log_info "Container logs:"
docker-compose -f "$COMPOSE_FILE" logs --tail=50
# Rollback
log_warn "Attempting rollback..."
docker-compose -f "$COMPOSE_FILE" down
exit 1
fi
# ============================================
# Post-deployment Tasks
# ============================================
log_info "Running post-deployment tasks..."
# Wait for database to be ready
log_info "Waiting for database to be ready..."
sleep 5
# Run migrations
log_info "Running database migrations..."
docker exec laravel_app php artisan migrate --force || log_warn "Migrations failed"
# Clear caches
log_info "Clearing caches..."
docker exec laravel_app php artisan cache:clear || log_warn "Cache clear failed"
docker exec laravel_app php artisan config:clear || log_warn "Config clear failed"
docker exec laravel_app php artisan view:clear || log_warn "View clear failed"
# Optimize
log_info "Optimizing application..."
docker exec laravel_app php artisan config:cache || log_warn "Config cache failed"
docker exec laravel_app php artisan route:cache || log_warn "Route cache failed"
docker exec laravel_app php artisan view:cache || log_warn "View cache failed"
# ============================================
# Health Check
# ============================================
log_info "Performing health check..."
MAX_RETRIES=30
RETRY_COUNT=0
HEALTH_CHECK_URL="http://localhost:8080"
while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
if curl -f -s "$HEALTH_CHECK_URL" > /dev/null 2>&1; then
log_info "✅ Application is healthy!"
break
fi
log_info "⏳ Waiting for application... ($RETRY_COUNT/$MAX_RETRIES)"
sleep 5
RETRY_COUNT=$((RETRY_COUNT + 1))
done
if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
log_error "Health check failed after $MAX_RETRIES attempts"
# Show recent logs
log_info "Recent application logs:"
docker-compose -f "$COMPOSE_FILE" logs --tail=100
exit 1
fi
# ============================================
# Display Status
# ============================================
log_info "Deployment completed successfully! 🚀"
log_info "Container status:"
docker-compose -f "$COMPOSE_FILE" ps
log_info ""
log_info "==================================="
log_info "Application URL: http://$(hostname -I | awk '{print $1}'):8080"
log_info "==================================="
log_info ""
log_info "Useful commands:"
log_info " - View logs: docker-compose -f $COMPOSE_FILE logs -f"
log_info " - Restart: docker-compose -f $COMPOSE_FILE restart"
log_info " - Stop: docker-compose -f $COMPOSE_FILE down"
log_info " - Shell access: docker exec -it laravel_app sh"
# ============================================
# Cleanup
# ============================================
log_info "Cleaning up deployment artifacts..."
rm -f laravel-app.tar.gz
log_info "Deployment script completed!"
exit 0