APBoard v3 · Dokumentation

Dokumentation

Alles was du brauchst, um APBoard zu installieren, zu konfigurieren und zu betreiben – ausführlich erklärt, auch für absolute Einsteiger.

APBoard › Dokumentation › Fehlerbehebung

Fehlerbehebung

Häufige Probleme und ihre Lösungen — geordnet nach Themenbereich. Wenn du dein Problem hier nicht findest, schau ins Forum oder öffne ein Issue auf GitLab.

Installation & Start

Container startet nicht (Docker)

Prüfe zuerst die Container-Logs:

bash 
docker compose logs apboard
docker compose logs db
docker compose ps

Häufige Ursachen:

  • Port bereits belegt: Ports 80/443 werden von einem anderen Prozess genutzt → ss -tlnp | grep ':80'
  • Fehler in der .env: Syntaxfehler, fehlende Pflichtfelder → .env prüfen
  • Datenbankcontainer nicht bereit: Manchmal startet der APBoard-Container bevor die DB fertig ist → docker compose restart apboard

Port 80 / 443 bereits belegt

bash 
# Welcher Prozess belegt den Port?
ss -tlnp | grep ':80'
ss -tlnp | grep ':443'

# Nginx oder Apache stoppen:
sudo systemctl stop nginx
sudo systemctl stop apache2

# Autostart deaktivieren damit es beim Reboot nicht wieder startet:
sudo systemctl disable nginx
sudo systemctl disable apache2

Datenbank-Verbindungsfehler

Symptom: Fehlermeldung „SQLSTATE[HY000] [2002] Connection refused" oder ähnliches.

  • Bei Docker: Ist DB_HOST=db in der .env? (Nicht localhost!)
  • Stimmt das Datenbankpasswort (DB_PASSWORD) mit dem was beim ersten Start gesetzt wurde?
  • Läuft der Datenbankcontainer? → docker compose ps
bash 
# Docker: Direkt in die Datenbank einloggen zum Testen
docker compose exec db mysql -u apboard -p

Web-Installer zeigt „Already installed"

APBoard erkennt eine vorhandene Installation und blockiert den Installer. Falls du eine Neuinstallation erzwingen willst (Achtung: löscht alle Daten!):

bash 
# LAMP: Installations-Lock-Datei entfernen
rm /var/www/forum/storage/installed.lock

# Docker:
docker compose exec apboard rm /var/www/html/storage/installed.lock

HTTP / HTTPS / Domain

Domain zeigt nicht auf den Server / HTTPS funktioniert nicht

bash 
# DNS prüfen:
nslookup forum.meine-domain.de
dig forum.meine-domain.de +short

# Ist Port 80 erreichbar? (von außen)
curl -v http://forum.meine-domain.de/

Let's Encrypt / Certbot benötigt, dass Port 80 öffentlich erreichbar ist und die Domain bereits auf den Server zeigt. DNS-Propagation kann bis zu 24 Stunden dauern.

HTTPS-Zertifikat wird nicht ausgestellt (Traefik)

bash 
# Traefik-Logs auf ACME-Fehler prüfen:
docker compose logs traefik | grep -i "acme\|certificate\|error"

# Ist Port 80 in der Firewall frei?
ufw status | grep 80

Häufige Ursachen:

  • Port 80 ist von einer Firewall gesperrt
  • Domain zeigt noch nicht auf den Server (DNS noch nicht propagiert)
  • Rate-Limit von Let's Encrypt überschritten (max. 5 Zertifikate pro Domain/Woche)
  • acme.json hat falsche Rechte → muss 600 sein: chmod 600 acme.json

Seite lädt, aber CSS und Bilder fehlen

Ursache: APP_URL in der .env stimmt nicht mit der tatsächlichen URL überein. Der Wert muss exakt lauten, z.B. https://forum.meine-domain.de — kein abschließender Schrägstrich, inkl. https://.

Nach Änderung der .env bei Docker:

bash 
docker compose restart apboard

Mixed Content Fehler (HTTPS-Seite lädt HTTP-Ressourcen)

Prüfe ob APP_URL mit https:// beginnt. Wenn das Forum hinter einem Reverse Proxy läuft, stelle sicher, dass der Header X-Forwarded-Proto: https gesetzt wird.

PHP / LAMP

500 Internal Server Error

Apache-Logs prüfen:

bash 
tail -100 /var/log/apache2/forum-error.log
# oder wenn du eigene Log-Pfade konfiguriert hast:
tail -100 /var/log/apache2/DEIN-FORUM-error.log

Häufige Ursachen:

  • Fehlende PHP-Erweiterung → im Log steht welche fehlt
  • Falsche Dateirechte auf storage/ oder bootstrap/cache/
  • Syntaxfehler in einer PHP-Datei nach einem Update
  • APP_KEY nicht gesetzt → php artisan key:generate

URL-Routing funktioniert nicht (404 auf allen Seiten außer Index)

Ursache: mod_rewrite nicht aktiviert oder AllowOverride All fehlt.

bash 
sudo a2enmod rewrite
sudo systemctl reload apache2

Prüfe die Apache VirtualHost-Konfiguration: Im <Directory>-Block muss AllowOverride All stehen.

Uploads schlagen fehl

Prüfe die PHP-Limits in der php.ini:

bash 
php -i | grep -E "upload_max_filesize|post_max_size|memory_limit"

Typische Werte die erhöht werden sollten: upload_max_filesize = 20M, post_max_size = 25M. Ändere diese in /etc/php/8.5/apache2/php.ini und lade Apache neu.

E-Mail

E-Mails kommen nicht an

  1. Prüfe die SMTP-Daten in der .env — Host, Port, Username, Passwort
  2. Prüfe den Spam-Ordner des Empfängers
  3. Teste die SMTP-Verbindung manuell:
bash 
# Docker:
docker compose exec apboard php artisan tinker
# Dann: Mail::raw('Test', fn($m) => $m->to('test@example.com')->subject('Test'));

# LAMP:
php artisan tinker

Gmail: Authentifizierung schlägt fehl

Gmail erlaubt keine direkten SMTP-Verbindungen mit dem Account-Passwort wenn 2FA aktiv ist. Erstelle ein App-Passwort unter myaccount.google.com/apppasswords und nutze das in der .env.

E-Mails landen im Spam

Das ist ein häufiges Problem bei günstigen VPS. Lösungen:

  • Richte SPF-, DKIM- und DMARC-DNS-Einträge für deine Domain ein
  • Nutze einen externen E-Mail-Dienst statt den Server direkt (mailbox.org, Gmail, Postmark, Mailgun etc.)
  • Stelle sicher, dass der MAIL_FROM_ADDRESS zur Domain des Servers passt

Sonstiges

Forum lädt extrem langsam

  • Prüfe ob genug RAM auf dem Server verfügbar ist: free -h
  • Schau in die APBoard-Fehler-Logs auf Warnungen
  • Stelle sicher dass der Opcache für PHP aktiv ist: php -r "echo opcache_get_status()['opcache_enabled'];"
  • Bei Docker: Überprüfe ob der Container genug Ressourcen hat: docker stats

Nach dem Update funktioniert das Forum nicht mehr

Prüfe die Logs auf Fehlermeldungen. Häufig hilft:

bash 
# Cache leeren:
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# Oder bei Docker:
docker compose exec apboard php artisan cache:clear
docker compose exec apboard php artisan config:clear

Falls das nicht hilft, spiele das Backup ein. Siehe APBoard aktualisieren → Rollback im Notfall.

Ich habe mein Admin-Passwort vergessen

bash 
# Passwort zurücksetzen (ersetze BENUTZERNAME):
# Docker:
docker compose exec apboard php artisan user:password BENUTZERNAME

# LAMP:
php artisan user:password BENUTZERNAME

Ich habe noch ein anderes Problem

Schau ins APBoard Forum oder öffne ein Issue auf GitLab. Beschreibe dabei:

  • Welche Installation (Docker / LAMP)?
  • Was genau passiert / was du erwartet hattest?
  • Relevante Fehlermeldungen aus den Logs
  • APBoard-Version (git log --oneline -1 oder im Admin-Panel)
Zurück APBoard aktualisieren