This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Deployment — PhorgeRunner (Production)

Zweck: Dieses Dokument beschreibt, wie das Docker‑Image gebaut, verteilt und in Production betrieben wird. Es enthält reproduzierbare Schritte für Build, Start, Konfiguration, Monitoring, Rollback und Upgrade.

1. Image build & Registry

• Lokaler Build:

# Build image (tag mit semantischer Version oder CI-Build-Nummer)
docker build -t phorgerunner:1.0.0 .

# Optional: Tag für Registry
docker tag phorgerunner:1.0.0 registry.example.org/phorgerunner:1.0.0

# Push
docker push registry.example.org/phorgerunner:1.0.0

• Empfehlung: CI (GitHub Actions / GitLab CI) automatisiert Build + Push auf Tag/Branch. Verwende immutable tags (semver + build SHA).

2. Production start (Optionen)

• Docker Compose (einfach): erstelle docker-compose.prod.yml mit gesetzten Umgebungsvariablen und Volumes. Beispiel minimal:

version: '3.8'
services:
  app:
    image: registry.example.org/phorgerunner:1.0.0
    environment:
      - DB_HOST=mysql
      - API_URL=https://phorge.example.org/api
    volumes:
      - /var/lib/phorgerunner/logs:/var/log/phorgerunner
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL","php -r 'exit(file_exists("/app/config/config.php")?0:1);'"]
      interval: 30s
      timeout: 5s
      retries: 3

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=secret
      - MYSQL_DATABASE=phorgerunner
      - MYSQL_USER=phorge
      - MYSQL_PASSWORD=secret
    volumes:
      - /var/lib/phorgerunner/mysql:/var/lib/mysql

• Systemd + docker run (server): Beispiel systemd unit kann docker run --rm -d ... oder docker compose up -d starten.

3. Environment-Variablen für Production (Beispiel)

• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS

• API_URL, API_TOKEN (vorsichtig: Secrets)

• LOG_MODE (file/db/console), LOG_DIR

• APP_VERSION (setzt sich idealerweise aus CI-Build)

• Secrets: Verwende Docker Secrets, a secret manager (Vault) oder host‑level env files with strict perms. Keine Secrets im VCS.

4. Volumes / Mounts

• Logs: mount host directory /var/lib/phorgerunner/logs → Container /var/log/phorgerunner (oder Pfad, der in config.php konfiguriert ist).
• Datenbank: Best practice = verwalteter DB-Service (RDS, managed) oder Host‑mounted volume /var/lib/phorgerunner/mysql.
• Config: config.php kann via entrypoint erzeugt werden oder per Volume gemountet (empfohlen: entrypoint + env + secret injection).

5. Monitoring / Health-Checks

• Docker healthcheck für Container‑Liveness (siehe Compose-Beispiel).
• Exporter/metrics: Wenn nötig, instrumentieren oder exportieren Logs → SIEM (Elastic, Loki) und nutzen Docker logging driver (gelf/fluentd).
• Alerts: Healthcheck failures, high error rates in logs, DB connection failures.

6. Rollback-Strategie

• Tag images immutably: registry.example.org/phorgerunner:1.0.0 und :1.0.1.
• Rollback = docker pull registry.example.org/phorgerunner:1.0.0 && docker-compose -f docker-compose.prod.yml up -d oder docker run vorherigen Tags.
• Für zero-downtime deploys: verwende orchestrator (Kubernetes) oder blue/green mittels proxy (nginx) vor den Runner‑Endpunkten.

7. Scaling

• PhorgeRunner ist ein CLI‑Task-Runner. Wenn mehrere Instanzen nötig sind, starte mehrere Replica‑Container und koordiniere Arbeit via Queue/DB locks.
• Verteile Last: wenn Runner Polling macht, begrenze Poll‑Interval oder setze zentralen Scheduler.

8. Upgrade-Prozess

1. Build and push new image.
2. Test image in staging environment (run compose with staging config).
3. Pull and restart production service (rolling restart if multiple replicas).
4. Monitor logs & healthchecks.
5. If issues, rollback to previous image tag.

9. Security & Permissions

• Non-root user inside image (already configured in Dockerfile).
• Ensure mounted logs dir ownership/permissions allow container user to write.
• Limit network access to necessary endpoints.

10. Troubleshooting & checks

• Check logs on host: /var/lib/phorgerunner/logs and docker logs.
• docker compose -f docker-compose.prod.yml logs -f app
• Health: docker inspect --format='{{json .State.Health}}' <container>

11. Definition of Done

• Dokumentation im Wiki unter "Deployment" (dieses Dokument).
• Alle Schritte sind reproduzierbar; mindestens ein Test-Deployment in Staging wurde durchgeführt.

---

Wenn du magst, schreibe ich noch ein docker-compose.prod.yml Beispiel-File in the repo and a small deploy.sh helper for pulling new images and restarting the service. Soll ich das anlegen? (Ja / Nein)

Deployment - Installation auf dem Wikonia Server

Diese Seite dokumentiert die produktive Installation von PhorgeRunner auf dem Wikonia-Server.

ℹ️ Für lokale Entwicklung siehe: Dev-Guide

---

Voraussetzungen auf dem Server

• PHP 7.4+ (meist bereits vorhanden bei Wikonia-Hosting)
• MariaDB/MySQL Server (mit eigenem PhorgeRunner-Benutzer)
• SSH/Kommandozeilen-Zugriff
• Cronjob-Zugriff

---

Installationsschritte

1. Repository klonen

cd /home/wikonia/public_html  # oder passender Pfad
git clone https://git.wikonia.net/WIKONIA/phorgerunner.git
cd phorgerunner

2. Produktive Konfiguration erstellen

cp config/config.template.php config/config.php
nano config/config.php

Einstellungen für Wikonia:

return [
    // Datenbank auf Wikonia
    'db_host'     => 'localhost',
    'db_name'     => '***DB NAME***',
    'db_user'     => '***DB USER***',  // Eigener Benutzer!
    'db_pass'     => '*** SICHERES PASSWORT ***',
    
    // Wikonia Phorge-Instanz
    'api_url'     => 'https://phorge.wikonia.net/api',
    'api_token'   => '*** API TOKEN ***',
    'api_timeout' => 30,
    
    // Logging: vorwiegend DB, Datei als Fallback
    'log_mode'    => 'db',
    'log_level'   => 'info',
    'log_dual'    => true,
    'log_dir'     => __DIR__ . '/../logs',
    'log_file'    => [
        'app'   => 'app.log',
        'error' => 'error.log',
    ]
];

3. Datenbank einrichten

SSH in Wikonia-Server:

mysql -u root -p

Dann in MySQL:

CREATE DATABASE wikonia_phorgerunner CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'phorgerunner_bot'@'localhost' IDENTIFIED BY '*** SICHERES PASSWORT ***';
GRANT ALL ON wikonia_phorgerunner.* TO 'phorgerunner_bot'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Schema laden:

mysql -u phorgerunner_bot -p wikonia_phorgerunner < sql/create.sql

4. Logs-Verzeichnis vorbereiten

mkdir -p logs
chmod 755 logs
chown www-data:www-data logs  # Falls Webserver auch schreiben soll

5. API-Token erstellen

1. Melde dich in phorge.wikonia.net an
2. Gehe zu Settings → Conduit API Tokens
3. Erstelle einen neuen Token für den Bot (z.B. "PhorgeRunner")
4. Kopiere den Token in config.php

6. Cronjobs einrichten

Beispiel: Task alle 6 Stunden ausführen

# Crontab öffnen
crontab -e

# Zeile hinzufügen:
0 */6 * * * cd /home/wikonia/public_html/phorgerunner && php cli/main.php >> logs/cron.log 2>&1

Für tägliche Wartungs-Tickets (z.B. um 02:00 Uhr):

0 2 * * * cd /home/wikonia/public_html/phorgerunner && php cli/daily-maintenance.php >> logs/cron.log 2>&1

Schema-Refresh (Custom-Felder automatisch aktualisieren)

Das Projekt enthält ein Tool zum Erkennen von benutzerdefinierten Maniphest-Feldern und zum Schreiben von zwei JSON-Dateien: var/schemas/maniphest.custom.json und var/schemas/maniphest.standard.json.

Empfohlenes Cron-Beispiel (täglich um 03:30):

30 3 * * * cd /home/wikonia/public_html/phorgerunner && ./scripts/update_schemas.sh >> logs/schema_refresh.log 2>&1

CI-Beispiel (GitLab CI, nur als geplanten Job):

schema_refresh:
  stage: maintenance
  image: docker:stable
  services:
    - docker:dind
  script:
    - docker compose -f docker-compose.yml exec -T app php /app/cli/schema_refresh.php maniphest
  only:
    - schedules

Hinweis: scripts/update_schemas.sh versucht zunächst docker compose zu verwenden und führt sonst php cli/schema_refresh.php maniphest lokal aus.

7. Test durchführen

Manuell eine Task ausführen:

cd /home/wikonia/public_html/phorgerunner
php cli/main.php

Log prüfen:

tail -f logs/app.log

---

Web-Frontend (optional)

Falls ein Web-Frontend später aktiviert werden soll:

.htaccess-Schutz

In public/.htaccess:

# IP-Schutz (z.B. nur Wikonia-Server)
<RequireAll>
    Require ip 192.168.1.0/24
</RequireAll>

# Oder HTTP-Auth
AuthType Basic
AuthName "PhorgeRunner Admin"
AuthUserFile /home/wikonia/.htpasswd
Require valid-user

Apache-Konfiguration

VirtualHost-Eintrag für runner.wikonia.net (optional):

<VirtualHost *:443>
    ServerName runner.wikonia.net
    DocumentRoot /home/wikonia/public_html/phorgerunner/public
    
    <Directory /home/wikonia/public_html/phorgerunner/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    SSLEngine on
    SSLCertificateFile /path/to/cert.pem
    SSLCertificateKeyFile /path/to/key.pem
</VirtualHost>

---

Wartung & Updates

Updates einspielen

cd /home/wikonia/public_html/phorgerunner
git pull origin main
# Falls neue Spalten nötig: SQL-Migrations einspielen
mysql -u phorgerunner_bot -p wikonia_phorgerunner < sql/migrations.sql

Logs säubern (optional)

# Alte Logs archivieren (älter als 30 Tage)
find logs/ -name "*.log" -mtime +30 -delete

Datenbank säubern

# Beispiel: Logs älter als 90 Tage aus DB löschen
mysql -u phorgerunner_bot -p wikonia_phorgerunner -e \
  "DELETE FROM logs WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY);"

---

Troubleshooting

"API-Token ungültig"

• Token prüfen in config.php
• Token in Phorge erneuern (Settings → Conduit)

"Datenbank-Fehler"

• MySQL-Benutzer prüft? mysql -u phorgerunner_bot -p -e "SELECT 1;"
• Schema vollständig geladen? mysql -u phorgerunner_bot -p wikonia_phorgerunner -e "SHOW TABLES;"

Cronjob läuft nicht

• Cronjob-Logs prüfen: cat /var/log/syslog | grep CRON
• Pfade absolut? which php verwenden

---

Siehe auch: Sicherheit, Cron-Jobs, Dev-Guide