FiveNet konfigurieren

Nutzen Sie diese Anleitung, nachdem Sie eine Bereitstellungsmethode gewählt haben und bevor Sie DBSync oder das FiveM-Plugin einrichten. Sie behandelt die minimale Konfiguration für eine funktionierende FiveNet-Installation.

Eine vollständige Übersicht aller Optionen und Standardwerte finden Sie in der Konfigurationsdatei-Referenz. Die Beispieldatei im FiveNet-Repository bleibt die maßgebliche Quelle für die vollständige Konfiguration.

Voraussetzungen

Stellen Sie sicher, dass Sie Folgendes haben:

• Eine unterstützte MySQL- oder MariaDB-Datenbank.
• Einen NATS-Server mit aktiviertem JetStream.
• Eine öffentliche HTTPS-URL für FiveNet oder einen Plan, die Instanz über einen Reverse-Proxy bereitzustellen.
• Einen Speicherort für Uploads: ein persistentes lokales Verzeichnis oder S3-kompatiblen Storage.
• Die config.example.yaml-Datei aus demselben Release wie das eingesetzte FiveNet-Image oder die verwendete Binary.

Wenn Sie Docker oder Helm verwenden, folgen Sie zuerst der jeweiligen Bereitstellungsanleitung, damit Sie wissen, wo die Konfigurationsdatei eingebunden wird und unter welchen internen Hostnamen die Dienste erreichbar sind.

1. config.yaml erstellen

Kopieren Sie die Beispieldatei und bewahren Sie sie bei den Bereitstellungsdateien auf. Bearbeiten Sie die Beispieldatei nicht direkt:

cp config.example.yaml config.yaml

Bei containerisierten Bereitstellungen binden Sie die fertige config.yaml an dem in der Bereitstellungsvorlage erwarteten Ort ein. FiveNet sucht zuerst im aktuellen Arbeitsverzeichnis und danach in /config nach der Datei.

2. Öffentliche URL konfigurieren

Setzen Sie die URL, die Benutzer im Browser öffnen:

http:
  publicURL: "https://fivenet.example.com"
  origins:
    - "https://fivenet.example.com"
  sessions:
    domain: "fivenet.example.com"

URL, Browser-Origin und Session-Domain müssen zur Domain Ihres Reverse-Proxys passen. Wenn Sie einen separaten Hostnamen für API- oder Plugin-Datenverkehr verwenden, ergänzen Sie die Origins entsprechend Ihrer Bereitstellung.

Prüfen Sie http.trustedProxies, wenn FiveNet hinter NGINX, Traefik, Cloudflare oder einem anderen Proxy läuft. Tragen Sie dort nur Proxy-Adressen oder Netzwerke ein, die Sie kontrollieren.

3. Secrets generieren und speichern

Generieren Sie eindeutige Werte für das Anwendungs-Secret, das Session-Cookie-Secret und das JWT-Secret. Bewahren Sie sie nach der Bereitstellung unverändert auf und committen Sie sie nicht in ein öffentliches Repository.

Zum Beispiel können Sie je nach Betriebssystem folgenden Befehl verwenden:

openssl rand -base64 32

[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

Tragen Sie die erzeugten Werte in den entsprechenden Optionen ein:

secret: "CHANGE_ME"

http:
  sessions:
    cookieSecret: "CHANGE_ME"

jwt:
  secret: "CHANGE_ME"

Eine spätere Änderung dieser Werte kann Sitzungen oder Tokens ungültig machen. Behandeln Sie Sync-API-Tokens ebenfalls als Secrets.

4. FiveNet-Datenbank konfigurieren

Setzen Sie database.dsn auf die von FiveNet verwendete MySQL- oder MariaDB-Datenbank:

database:
  dsn: "DB_USER:DB_PASS@tcp(DB_HOST:DB_PORT)/DB_NAME?collation=utf8mb4_unicode_ci&parseTime=True&loc=Europe%2FBerlin"

Verwenden Sie einen Datenbankbenutzer mit den für FiveNet-Migrationen und den normalen Betrieb erforderlichen Berechtigungen. Die konfigurierte Kollation sollte mit der Datenbank und den Tabellen übereinstimmen. Siehe Datenbankeinrichtung, wenn Migrationen Kollations- oder Fremdschlüsselfehler melden.

5. NATS konfigurieren

Setzen Sie nats.url auf den NATS-Server und stellen Sie sicher, dass JetStream aktiviert ist:

nats:
  url: "nats://USER:PASSWORD@NATS_HOST:4222"

Wenn FiveNet in Docker Compose läuft, verwenden Sie den Namen des NATS-Dienstes als Hostnamen, z. B. nats, und nicht localhost. In Kubernetes verwenden Sie den DNS-Namen des NATS-Service.

6. Sync-API aktivieren

DBSync und das FiveM-Plugin verwenden die Sync-API. Aktivieren Sie sie und erstellen Sie mindestens ein langes, eindeutiges Token:

sync:
  enabled: true
  apiTokens:
    - "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN"

Verwenden Sie das Token nur in den DBSync- und Plugin-Konfigurationen, die es benötigen. Wenn Sie das Token austauschen, aktualisieren Sie beide Integrationen.

7. Upload-Speicher konfigurieren

Der standardmäßige Dateisystem-Speicher ist für eine einzelne Instanz geeignet, wenn das Verzeichnis persistent ist:

storage:
  type: filesystem
  filesystem:
    path: /data

Stellen Sie sicher, dass /data in Docker oder Kubernetes durch ein persistentes Volume gesichert ist. Für mehrere Instanzen oder extern verwaltete Uploads konfigurieren Sie stattdessen den S3-kompatiblen Speicher. Siehe Erweiterte Konfiguration.

8. Zugriff auf die Erstkonfiguration gewähren

Geben Sie der Gruppe Ihres ersten Administrators Zugriff auf die Konfigurationseinstellungen:

auth:
  configAdminGroups:
    - admin

Alternativ können Sie auth.configAdminUsers für bestimmte Benutzer verwenden. Das erste Konto muss trotzdem erstellt und registriert werden, wie unter Ersteinrichtung abschließen beschrieben.

9. FiveNet starten und prüfen

Starten Sie die Bereitstellung mit dem für Ihre Installationsmethode passenden Befehl. Prüfen Sie anschließend:

• Der Server startet ohne Datenbank- oder NATS-Fehler.
• Datenbankmigrationen werden erfolgreich abgeschlossen.
• Die konfigurierte öffentliche URL ist über HTTPS erreichbar.
• Das erste Konto kann sich registrieren und anmelden.
• Der Upload-Speicher ist beschreibbar.

Wenn der Kernserver funktioniert, fahren Sie mit DBSync und anschließend mit Ersteinrichtung abschließen fort.