Deployment-Dokumentation

Übersicht

Dieses Dokument beschreibt den Deployment-Prozess für die Zwergen-Börse Website.

Voraussetzungen

Server-Anforderungen

• PHP: Version 8.0+ mit folgenden Extensions:
  • SQLite
  • Session
  • Mail (sendmail/postfix)
• Node.js: Version 18+ (für Build)
• Web-Server: Apache oder Nginx
• Git: Für Repository-Zugriff

Berechtigungen

• Schreibrechte für public/data/
• Ausführungsrechte für PHP
• SSH-Zugriff für Deployment

Deployment-Prozess

1. Repository vorbereiten

Lokal:

# Änderungen committen
git add .
git commit -m "Deployment: Beschreibung"

# Build ausführen
npm run build

# Build-Artefakte committen (optional)
git add public/
git commit -m "Build: Aktualisierte Artefakte"

2. Auf Server deployen

Option A: Forgejo Actions (empfohlen):

• Push auf main Branch → Automatisches Deployment
• Oder manuell: Repository → Actions → "Build and Deploy (rsync)" → "Run workflow"

Option B: Git-Pull (manuell):

# Auf Server
cd /path/to/website
git pull origin main
npm install
npm run build

Option C: rsync/scp (manuell):

# Lokal
rsync -avz --exclude 'node_modules' \
  --exclude '.git' \
  ./ user@server:/path/to/website/

3. Server-Konfiguration

Berechtigungen setzen:

chmod 755 public/data
chown www-data:www-data public/data

Web-Server konfigurieren:

• Document Root: /path/to/website/public
• PHP aktivieren
• .htaccess unterstützen (Apache)

4. Datenbank initialisieren

Die Datenbank wird automatisch beim ersten Zugriff erstellt. Manuell prüfen:

ls -la public/data/

5. Konfiguration prüfen

1. Admin-Login testen:

   • URL: https://domain.de/backend/web/admin_login.php
   • Passwort ist als Hash in der DB-Config (adminPasswordHash) hinterlegt
   • Falls unbekannt: Passwort-Reset im Login nutzen (sendet ein neues Passwort an operatorEmail)

2. Konfiguration setzen:

   • Event-Datum
   • Anmeldezeitraum
   • Nummernbereich
   • Organisator-E-Mail

3. Passwort ändern

6. Mail-Queue Cron einrichten (empfohlen)

Wenn die Mail-Queue aktiv ist (mailQueueEnabled=1), sollten Mails per Cron versendet werden:

• Cron Entry-Point (CLI-only): public/backend/cron/send_mail_queue.php

Beispiel (jede Minute):

* * * * * /usr/bin/php /path/to/website/public/backend/cron/send_mail_queue.php

Hinweise:

• Das Script blockt Webzugriff und läuft nur unter PHP_SAPI=cli.
• Rate-Limit und Status kann im Admin-Tab „Mail-Queue“ konfiguriert/überwacht werden.
• Logs:
  • Standard: $HOME/logs/mail-queue.log (wenn verfügbar), sonst public/data/mail-queue.log
  • Override: Env MAIL_QUEUE_LOG=/pfad/zur/logdatei

Mehr Details: Mail-Queue

Automatisches Deployment

Forgejo Actions (CI/CD)

Das Projekt verwendet Forgejo Actions für automatisches Build und Deployment.

Workflow: .forgejo/workflows/deploy-rsync.yml

Funktionsweise:

• Automatisches Deployment bei Push auf main Branch
• Manuelles Deployment über workflow_dispatch möglich
• Verwendet Docker-Image: git.home.schumbi.de/ralf/debian-bookworm-ssh-rsync:latest
• Deployment-Ziel: buschev.de:/var/www/virtual/buschev/doberaner-zwergenboerse.de

Workflow-Schritte:

1. Code auschecken
2. Node.js verifizieren
3. Dependencies installieren (npm install --legacy-peer-deps)
4. Projekt bauen (npm run build)
5. Build-Output verifizieren (prüft, ob public/ existiert und nicht leer ist)
6. SSH-Setup (Key-Konfiguration, Host-Key-Verifizierung)
7. Deployment via rsync (mit optimierten Parametern)

Benötigte Secrets in Forgejo:

• SSH_DEPLOY_KEY: Private SSH-Key für Server-Zugriff
• DEPLOY_USER: SSH-Benutzername für buschev.de
• DEPLOY_PORT (optional): SSH-Port (Standard: 22)

Runner-Konfiguration:

• Runner: arch (selbst-gehosteter Runner)
• Container: git.home.schumbi.de/ralf/debian-bookworm-ssh-rsync:latest
• Das Docker-Image enthält bereits Node.js 24, SSH und rsync

rsync-Parameter:

• -avz: Archive-Mode, verbose, komprimiert
• --delete: Löscht Dateien auf dem Server, die lokal nicht mehr existieren
• --exclude: Schützt Datenbank-Dateien (data/*.db, data/*.log)
• SSH-Optionen: StrictHostKeyChecking=accept-new für bessere Host-Key-Behandlung

Build-Verifizierung:

• Nach dem Build wird geprüft, ob public/ existiert und nicht leer ist
• Verhindert Deployment leerer oder fehlgeschlagener Builds

Dokumentation: Siehe .forgejo/README.md im Repository

Git Hooks (Legacy)

post-receive Hook (auf Server, falls kein CI/CD verwendet wird):

#!/bin/bash
cd /path/to/website
git --git-dir=.git --work-tree=. checkout -f
npm install
npm run build
chmod 755 public/data

Setup:

# Auf Server
cd /path/to/website.git/hooks
chmod +x post-receive

Konfiguration

Apache

Virtual Host:

<VirtualHost *:80>
    ServerName doberaner-zwergenboerse.de
    DocumentRoot /path/to/website/public
    
    <Directory /path/to/website/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/zwergenboerse_error.log
    CustomLog ${APACHE_LOG_DIR}/zwergenboerse_access.log combined
</VirtualHost>

.htaccess (in public/):

# Backend-Verzeichnis schützen
<Directory "backend">
    Options -Indexes
    AllowOverride None
</Directory>

# Datenbank-Dateien schützen
<FilesMatch "\.(db|sqlite3?|dat|log)$">
    Require all denied
</FilesMatch>

Nginx

Server Block:

server {
    listen 80;
    server_name doberaner-zwergenboerse.de;
    root /path/to/website/public;
    index index.html index.php;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /backend/ {
        deny all;
    }

    location ~ \.(db|sqlite3?|dat|log)$ {
        deny all;
    }
}

Rollback

Bei Problemen

1. Vorherige Version wiederherstellen:

   git checkout <previous-commit>
   npm run build
   

2. Backup wiederherstellen:

   cp backup/zwergenboerse_YYYYMMDD.db public/data/zwergenboerse.db
   

3. Web-Server neu starten:

   sudo systemctl restart apache2
   # oder
   sudo systemctl restart nginx
   

Wartung

Regelmäßige Aufgaben

1. Backups:

   # Datenbank
   cp public/data/zwergenboerse.db backup/zwergenboerse_$(date +%Y%m%d).db
   
   # Gesamtes public/ Verzeichnis
   tar -czf backup/public_$(date +%Y%m%d).tar.gz public/
   

2. Logs prüfen:

   • Web-Server Logs
   • PHP Error Logs
   • Admin-Actions Log

3. Updates:

   • Dependencies: npm update
   • PHP-Updates
   • System-Updates

Monitoring

Zu überwachen:

• Disk-Space (public/data/)
• PHP-Error-Logs
• Web-Server-Logs
• Anmeldeanzahl (Counter)

Troubleshooting

Build schlägt fehl

Problem: npm run build fehlgeschlagen

Lösung:

• Node.js-Version prüfen
• Dependencies neu installieren: rm -rf node_modules && npm install
• Fehlermeldungen prüfen

Datenbank nicht beschreibbar

Problem: Database directory is not writable

Lösung:

chmod 755 public/data
chown www-data:www-data public/data

E-Mails werden nicht versendet

Problem: E-Mails kommen nicht an

Lösung:

• sendmail/postfix prüfen
• PHP mail() Funktion testen
• Error-Logs prüfen
• SMTP-Konfiguration prüfen

404-Fehler

Problem: Seiten werden nicht gefunden

Lösung:

• Document Root prüfen
• .htaccess prüfen (Apache)
• URL-Rewriting konfigurieren
• Build-Artefakte prüfen

Best Practices

Vor Deployment

• Tests lokal durchführen
• Build erfolgreich
• Änderungen dokumentiert
• Backup erstellt

Nach Deployment

• Funktionen testen
• Admin-Login prüfen
• Anmeldeformular testen
• E-Mail-Versand testen
• Logs prüfen

Sicherheit

• Passwort geändert
• .htaccess konfiguriert
• Berechtigungen gesetzt
• Error-Display deaktiviert

Checkliste

Initiales Deployment

• Repository geklont
• Dependencies installiert
• Build ausgeführt
• Web-Server konfiguriert
• Berechtigungen gesetzt
• Admin-Login getestet
• Konfiguration gesetzt
• Passwort geändert
• Backup-Strategie implementiert

Regelmäßiges Deployment

• Änderungen committet
• Build lokal getestet
• Auf Server deployed
• Funktionen getestet
• Backup erstellt