Colab Backend

Dieses Repository enthält die Backend-Software für das Unity-Projekt, der Universität Wuppertal.

Features

• Verwaltung von Nutzerprofilen und -daten
• Rollen und Rechteverwaltung
• Datei-Upload
• Bespielung von Game Objects

Standart Email und Passwort

Bitte Email und Passwort nach der Installation ändern. Email: admin@admin.de Passwort: admin

Bedienungsanleitung

• Anlegen neuer Nutzer
• Benutzer Freischalten
• Passwort oder Email ändern
• Neues Whiteboard Anlegen
• Versionnummerupdaten
• Rechte ändern
• Profil bearbeiten

Installation auf dem Server

• Voraussetzungen
• Voraussetzungen
• Installation
• Anwendung einrichten
• Datenbank mit Docker
• Datenbank ohne Docker
• Backup System Starten

Anlegen neuer Nutzer

Schritte:

1. Navigieren Sie im Adminbereich zum Menüpunkt "Benutzer".
2. Wählen Sie die Option "Benutzer erstellen".
3. Füllen Sie das Formular mit den benötigten Informationen aus, wie Benutzername, E-Mail, Passwort, Rolle und ob der Benutzer freigeschaltet werden soll.
4. Überprüfen Sie die eingegebenen Informationen und klicken Sie auf "Erstellen", um den neuen Nutzer anzulegen.

Benutzer Freischalten

Schritte:

1. Navigieren Sie im Adminbereich zum Menüpunkt "Benutzer".
2. Suchen Sie den zu aktivierenden Benutzer in der Liste.
3. Klicken Sie auf die drei Punkte, um den Benutzer zu bearbeiten.
4. Aktivieren Sie die Checkbox "Aktiv".
5. Überprüfen Sie die eingegebenen Informationen und klicken Sie auf "Speichern", um die Einstellung zu speichern.

Passwort oder Email ändern

Schritte:

1. Navigieren Sie im Adminbereich zum Menüpunkt "Benutzer".
2. Suchen Sie den zu bearbeitenden Benutzer in der Liste.
3. Klicken Sie auf die drei Punkte, um den Benutzer zu bearbeiten.
4. Hier können Sie die E-Mail-Adresse des Nutzers ändern oder das Passwort zurücksetzen.
5. Überprüfen Sie die eingegebenen Informationen und klicken Sie auf "Speichern", um die Einstellung zu speichern.

Rechte ändern

Schritte:

1. Navigieren Sie im Adminbereich zum Menüpunkt "Benutzer".
2. Suchen Sie den zu bearbeitenden Benutzer in der Liste.
3. Klicken Sie auf die drei Punkte, um den Benutzer zu bearbeiten.
4. Wählen Sie im Auswahlmenü "Rollen" die gewünschte Rolle des Nutzers.
5. Überprüfen Sie die eingegebenen Informationen und klicken Sie auf "Speichern", um die Einstellung zu speichern.

Neues Whiteboard Anlegen

Schritte:

1. Navigieren Sie im Adminbereich zum Menüpunkt "Dateien".
2. Dort sind alle bestehenden Whiteboard-Dateien aufgelistet. Die Spalte "Id" ist die relevanteste und wird in der Unity-Anwendung als Wert zur Verknüpfung verwendet.
3. Klicken Sie auf "Datei erstellen".
4. Hier können Sie nun eine beliebige Datei hochladen.
5. Überprüfen Sie die eingegebenen Informationen und klicken Sie auf "Speichern", um die Einstellung zu speichern.
6. Den erstellten Eintrag können Sie nun in Unity verwenden.

Versionnummerupdaten

Schritte: Die Versionnummer wird im Normalfall von der Unity Applikation selbständig geupdatet sollte dies nicht passieren. Können sie das wie folgt ändern.

1. Im Adminbereich zum Menüpunkt "Server Config" navigieren.
2. Aktuelle Versionnummer eingeben.
3. Auf "Speichern" klicken, um die Einstellung zu speichern.

Profil bearbeiten

1. Im Adminbereich zum Menüpunkt "Profil" navigieren.
2. Änderungen am eigenen Profil vornehmen.
3. Auf "Speichern" klicken, um die Einstellung zu speichern.

Voraussetzungen

• PHP (Version 8.2)
• Composer (Installations Link)
• Docker (Installations Link)
• Symfony CLI (Installations Link)
• Linux Webserver (Apache oder Nginx)

Installation

Laden sie das Backend auf ihren Webserver hoch. Zu dem Pfad Worauf ihre Domain verweist. Beispielsweise: "/var/www/html/qf-colab-backend"

Hierfür gibt es Zwei Optionen:

1. Option Git:
   Installieren sie Git auf ihren Webserver und clonen sie das Repository in das gewünschte Verzeichnis.

git clone <Gitlab-Repository-URL>

2. Option Manueller Fileupload
   Laden sie per FTP das gesamte GIT Verzeichnis hoch in das gewünschte Verzeichnis.

Damit das Backend einwandfrei läuft müssen die für das Backend benötigte Libarys installiert werden.

Wechseln sie dazu in der Hauptverzeichnis der Anwendung.

Anwendung einrichten

1. Installiere die Composer-Abhängigkeiten: Sollte es bei der installation zu Fehlern kommen bitte vorher die Datenbank einrichten.

composer install

2. Bereiten sie das Eviroment vor:

php bin/console cache:clear  

3. Zum nutzen der API müssen nun Keys erstellt werden:

php bin/console lexik:jwt:generate-keypair 

Datenbank mit Docker

Um die Datenbank mit hilfe von Docker aufzusetzen führen sie folgende Installationsanleitung durch.

Zuerst Docker allgemein Installieren mit folgende Anleitungen: https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository

Danach das Docker Compose Repository: https://docs.docker.com/compose/install/linux/#install-using-the-repository

1. Datenbank Image erstellen:

docker compose up --build

2. Starten der Datenbank im Hintergrund:

docker compose up -d

3. Installiere die Composer-Abhängigkeiten (Zum sicherstellen das alle packages da sind):

composer install

4. Migration durchführen Anlegen der Benötigten Tabellen auf der Datenbank:

symfony console doctrine:migrations:migrate

5. Führe Data Fixtures aus, um Initialdaten zu laden:

symfony console --env=dev doctrine:fixtures:load 

Probleme mit dem Port bei der Verbindung zur Datenbank. Portauslesung durchführen mit dem Befehl:

symfony var:export --multiline

Datenbank ohne Docker

Um da Colab Backend zu verwenden ohne Docker müssen sie eine Datei anpassen, dies erkläre ich im folgenden.
Im Hauptverzeichnis der Anwendung befinden sich die ".env" die muss wie folgt bearbeitet werden.

1. Öffnen sie die ".env" Datei und bearbeiten sie die folgende Konstante, setzen sie die IP und den PORT ihrer Datenbank ein:

DATABASE_URL="mysql://root:Xr6ONXN4ng^4@<IP>:<PORT>/colab?sslmode=disable&charset=utf8mb4"

2. Migration durchführen Anlegen der Benötigten Tabellen auf der Datenbank:

symfony console doctrine:migrations:migrate

4. Führe Data Fixtures aus, um Initialdaten zu laden:

symfony console --env=dev doctrine:fixtures:load 

Probleme mit dem Port bei der Verbindung zur Datenbank. Portauslesung durchführen mit dem Befehl:

symfony var:export --multiline

Datenbank-Backup & Wiederherstellung (Colab Backend)

Diese Anleitung erklärt, wie du das automatische tägliche Backup der Datenbank aktivierst
und wie du im Notfall ein gespeichertes Backup wiederherstellen kannst.

---

1. Automatisches Backup aktivieren (Cronjob)

Der Cronjob erstellt jeden Tag automatisch ein Backup der MySQL-Datenbank
aus dem Docker-Container qf-colab-backend-database-1
und speichert es im Projektordner unter backup/.

---

Schritt-für-Schritt-Anleitung

1. Auf dem Server anmelden

2. Cronjob öffnen

   crontab -e

3. Folgende Zeile am Ende hinzufügen

   0 3 * * * cd /var/www/html/qf-colab-backend && /usr/bin/php bin/console app:backup:db --env=prod >> var/log/db_backup.log 2>&1

   💡 Erklärung:

   • 0 3 * * * → führt das Backup täglich um 03:00 Uhr nachts aus
   • /var/www/html/qf-colab-backend → Pfad zum Projekt (anpassen, falls anders)
   • >> var/log/db_backup.log 2>&1 → schreibt Ausgaben in eine Logdatei

4. Datei speichern und schließen

   • Wenn du den nano Editor nutzt:
     → CTRL + O, dann ENTER, dann CTRL + X

5. Überprüfen, ob Cron läuft

   systemctl status cron

   Wenn dort steht: active (running) → alles korrekt ✅

---

INFO: Alles weiter ab jetzt dient nur zum Testen, ob es klappt und Wiederherstellen der Datenbank muss nicht ausgeführt werden.

Log-Datei prüfen

Die Ausgaben und eventuelle Fehlermeldungen findest du hier:

cat var/log/db_backup.log

---

Backup manuell starten

Du kannst das Backup jederzeit auch manuell ausführen:

php bin/console app:backup:db

Die Sicherungsdateien liegen anschließend im Ordner:

backup/

---

2. Backup wiederherstellen (Restore)

Wenn du ein Backup einspielen möchtest, nutze diesen Befehl:

cat backup/colab-2025-10-06_12-10-00.sql | docker exec -i -e MYSQL_PWD=(`MYSQL_PWD`) qf-colab-backend-database-1 mysql -u root colab

💡 Wichtig:

• "colab-2025-10-06_12-10-00.sql ist" nur ein beispiel, schau im Backup Ordner welche genommen werden soll.
• Die Datenbank colab wird dabei überschrieben.
• Ersetze den Dateinamen durch dein gewünschtes Backup.
• Das Passwort (MYSQL_PWD) steht in deiner .env-Datei als DB_PASSWORD.
• Im Projekt Verzeichnis ausführen

---

Prüfung nach dem Restore

Datenbank prüfen:

docker exec -it qf-colab-backend-database-1 mysql -u root -p

Dann im MySQL-Fenster:

SHOW DATABASES;
USE colab;
SHOW TABLES;

---

Wichtige Orte & Befehle

Zweck	Pfad / Befehl
Cronjob anzeigen	crontab -l
Cron deaktivieren	crontab -r
Backup manuell starten	php bin/console app:backup:db

---

Hinweise

• Der Cronjob läuft auf Ubuntu-Servern standardmäßig.
  Prüfen kannst du das mit:

  systemctl status cron

• Alte Backups werden automatisch gelöscht (Rotation, Standard: 14 Tage).

• Wenn du Docker oder PHP auf einem anderen Pfad installiert hast,
  passe den Cronjob-Befehl entsprechend an.

---

Problembehandlung

Es kann hilfreich sein die Symfony CLI zu installieren, dieses kann schon bei der Installation Fehler beheben: https://symfony.com/download

Probleme bei der Docker installation hier sind zwei hilfreiche Seiten: https://github.com/dunglas/symfony-docker https://symfony.com/doc/current/setup/docker.html

Sollte es bei der Laufzeit zu dem Problem kommen das die Anwendung die Datenbank nicht findet. Führen folgenden befehl aus, dies startet das Docker image neu:

docker-compose up -d