> For the complete documentation index, see [llms.txt](https://crossban.thelukez.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://crossban.thelukez.com/de/dokumentation/self-hosting-a-discord-bot-on-a-vps.md).

# Eigener Discord-Bot auf einem VPS hosten

Dieser Leitfaden bietet einen Schritt-für-Schritt-Prozess, um den CrossBan Discord-Bot selbst auf einem [Virtual Private Server (VPS)](#user-content-fn-1)[^1]. CrossBan ist ein Bot zum Synchronisieren von Banns über mehrere Discord-Server hinweg, gebaut mit TypeScript, Discord.js und PostgreSQL. Er ist mit Docker containerisiert für einfache Bereitstellung.

{% hint style="info" %}
Dieser Bot ist unter der PolyForm Noncommercial License 1.0.0 lizenziert.\
Du darfst ihn nicht für kommerzielle Zwecke oder zur Gewinnerzielung verwenden.\
Self-Hosting ist nur für persönliche oder gemeinnützige Nutzung erlaubt.
{% endhint %}

## Voraussetzungen

### Minimale VPS-Anforderungen

* **Betriebssystem**: Ubuntu 22.04 LTS oder eine ähnliche Linux-Distribution (empfohlen für Docker-Kompatibilität).
* **Arbeitsspeicher**: Mindestens 2GB, weil Docker dafür bekannt ist, RAM zum Frühstück zu verzehren.
* **Speicher**: 10GB+ freier Speicherplatz (für Docker-Images, Datenbank und Logs). 20GB+ ist besser.
* **CPU**: 2 Kerne (ausreichend für moderaten Gebrauch).

{% hint style="info" %}
Ein Server kostet Geld - du solltest keine kostenlosen Hosting-Lösungen verwenden, weil du dort keine persönliche IP-Adresse bekommst, was zu Problemen mit deinem Bot führen kann.

Normalerweise kosten Server mit diesen Anforderungen etwa 3–5€ / Monat, abhängig vom Hosting-Anbieter.

Ein Server kostet nicht viel und ich würde Venocix empfehlen - eine sehr zuverlässige Hosting-Lösung aus Deutschland.

<a href="https://venocix.de/cart.php?a=add&#x26;pid=92" class="button primary">Server-Vorschlag</a>
{% endhint %}

### Software-Anforderungen

#### **Server-Anforderungen**

* **Docker**: Version 27+ (verwende die neueste Version, damit du sie längere Zeit nicht aktualisieren musst)
* **Docker Compose**: Version 2.39 (gleiches Denken wie oben)
* **Git**: Zum Klonen des Repositories.
* **SSH-Zugang**: Zu deinem VPS für Fernverwaltung.

#### **Lokale Anforderungen**

* Ein SSH-Client wie [Termius](https://termius.com/) um sicher eine Verbindung zu deinem VPS herzustellen und eine benutzerfreundliche Oberfläche zu haben.

#### Weitere Anforderungen

* Ein Discord-Bot-Token (erstelle eines im [Discord Developer Portal](https://discord.com/developers/applications)). Mehr dazu später.

***

## Bot einrichten

### Schritt 1: Bereite deinen VPS vor

1. **Verbinde dich mit deinem VPS** mit deinem SSH-Client.
2. **System aktualisieren**:

   ```bash
   sudo apt update && sudo apt upgrade
   ```

   *Denk daran, dass du aus Sicherheitsgründen das eingegebene Passwort nicht siehst.*
3. **Docker und Docker Compose installieren**: Bitte beziehe dich auf die offiziellen [Docker-Dokus](https://docs.docker.com/engine/install/) für die korrekte Installationsmethode für dein Betriebssystem.
4. **Git installieren**:

   ```bash
   sudo apt install git
   ```
5. **Installationen überprüfen**:

   ```bash
   docker --version
   docker compose version
   git --version
   ```

### Schritt 2: Repository klonen und einrichten

1. **Repository klonen**:

   ```bash
   git clone https://github.com/The-LukeZ/CrossBan.git
   cd CrossBan
   ```

2. **Umgebungsdatei erstellen**:
   * Kopiere die Beispiel-Umgebungsdatei:

     ```bash
     cp .env.example .env
     ```

   * Bearbeite `.env` mit deinen Daten:

     ```bash
     nano .env # öffnet einen einfachen Datei-Editor
     ```

     Fülle die Platzhalter aus.

### **Schritt 3: Lade den Bot auf deine Server ein**

1. Gehe zum Discord Developer Portal.

2. Deaktiviere den allgemeinen **Installationslink** und erlaube nur **Guild-Installation**.<br>

   <div align="center"><figure><img src="https://2525234079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3lpq6HV7nmiKLpSOZkGS%2Fuploads%2Fg9Bqqze1gA3LxgC8BgUC%2Fimage.png?alt=media&amp;token=d2c3b69c-0cc6-4217-bc60-c7d97c03faa3" alt=""><figcaption></figcaption></figure></div>

3. Gehe zur Bot-Seite und deaktiviere Public bot und regeneriere das Token deines Bots.<br>

   <figure><img src="https://2525234079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3lpq6HV7nmiKLpSOZkGS%2Fuploads%2FMTRqHAkD4KhdSqgddvfv%2F485610768-1f4efb96-e104-49f1-ae43-a77da590b314.png?alt=media&amp;token=03a5bd46-d54c-45a2-8b6e-0a813b436fb7" alt=""><figcaption><p>Deaktiviere Public bot, weil sonst jeder deinen Bot einladen kann - das willst du nicht.</p></figcaption></figure>

4. Unter deiner Bot-Anwendung gehe zu **OAuth2** > **OAuth2 URL-Generator**.

5. Wähle Scopes: `bot`, `applications.commands`.

6. Wähle Berechtigungen: **Mitglieder bannen**, **Audit-Log ansehen**, **Nachrichten senden**, **Slash-Befehle verwenden**.

7. Benutze die generierte URL, um den Bot in deine Server einzuladen.

### Schritt 4: Bot konfigurieren und starten

1. **Bot bauen und starten**:
   * Verwende die Docker Compose Datei:

     ```bash
     pnpm run docker:build
     ```
   * Dies baut die Docker-Images[^2], startet den Bot und die PostgreSQL-Datenbank und führt sie im Detached-Modus aus (damit sie im Hintergrund laufen, selbst wenn du die Verbindung zum Server trennst).<br>
2. **Setup überprüfen**:
   * Container-Status prüfen:

     ```bash
     docker compose ps
     ```
   * Logs ansehen:

     ```bash
     docker compose logs -f
     ```
   * Der Bot sollte in deinen Discord-Servern online erscheinen. Führe `/config` in Discord aus, um Einstellungen zu konfigurieren.<br>
3. **Erstkonfiguration in Discord**:
   * Benutze Slash-Befehle wie `/config sources-of-truth` um vertrauenswürdige Nutzer festzulegen.
   * Konfiguriere Bannsynchronisationseinstellungen pro Server.

### Schritt 4: Überwachung und Wartung

#### Logs

* Echtzeit-Logs ansehen:

  ```bash
  docker compose logs
  ```

#### Updates

* Ziehe den neuesten Code:

  ```bash
  # Gehe in das Verzeichnis, in dem der Code liegt
  cd CrossBan
  # Ziehe den neuesten Code
  git pull origin main
  ```
* Neustarten:

  ```bash
  pnpm run docker:restart
  ```

<details>

<summary>Hinweis für Entwickler</summary>

Ja, es wäre besser, das Image auch neu zu bauen, aber solange sich daran nichts ändert, funktioniert es auch nur durch Neustarten des Bots. Weitere Dokumentation wird hinzugefügt, wenn das nötig wird.

</details>

#### Backups

* Sichere das Datenbank-Volume:

  ```bash
  docker compose exec postgres pg_dump -U {POSTGRES_USER} {POSTGRES_DB} > backup.sql
  ```

  <mark style="color:roten;">**Denk daran, die Werte einzusetzen, die du in deiner**</mark><mark style="color:roten;">**&#x20;**</mark><mark style="color:roten;">**`.env`**</mark><mark style="color:roten;">**&#x20;**</mark><mark style="color:roten;">**Datei!**</mark>
* Speichere `backup.sql` sicher (z. B. außerhalb des VPS).

#### Bot stoppen

```
pnpm run docker:down
```

#### Neustarten

```
pnpm run docker:restart
```

***

## Fehlerbehebung

#### Häufige Probleme

* **Bot startet nicht**: Prüfe `.env` auf Fehler. Stelle sicher, dass `BOT_TOKEN` gültig ist und die Berechtigungen korrekt sind.
* **Datenbankverbindung fehlgeschlagen**: Überprüfe `DATABASE_URL` und dass PostgreSQL läuft (`docker compose ps`).
* **Berechtigungsfehler**: Stelle sicher, dass der Bot `Mitglieder bannen` und `Audit-Log ansehen` in allen Servern hat.
* **Container stürzt ab**: Verwende `docker compose logs` zur Diagnose. Häufige Ursachen: ungültige Umgebungsvariablen oder Port-Konflikte. Wenn ein Container in einer Neustart-Schleife steckt (Container starten neu, wenn sie fehlschlagen), stoppe die Container mit `pnpm run docker:down` und öffne ein GitHub-Issue, damit wir das gemeinsam lösen können.

#### Datenbank-Probleme

* Wenn PostgreSQL nicht startet, lösche das Volume und starte neu:

  ```bash
  docker compose down -v
  docker compose up -d --build
  ```

{% hint style="danger" %}
Dies löscht alle Daten; verwende es nur, wenn nötig.
{% endhint %}

#### Leistung

* Für stark frequentierte Server erhöhe die VPS-Ressourcen.

## Sicherheitsüberlegungen

* **Umgebungsvariablen**: Niemals `.env` zu Git committen (Das ist standardmäßig durch die `.gitignore` Datei gewährleistet).
* **Updates**: Halte Docker und das System aktuell, um Sicherheitslücken zu schließen.
* **Zugriff**: Beschränke SSH-Zugänge mit schlüsselbasierter Authentifikation. (Für fortgeschrittene Nutzer)

## Weitere Ressourcen

* [Discord.js Dokumentation](https://discord.js.org/docs/packages/discord.js)
* [Docker Compose Dokus](https://docs.docker.com/compose/)
* [PostgreSQL Dokus](https://www.postgresql.org/docs/)
* Das Repository: [CrossBan auf GitHub](https://github.com/The-LukeZ/CrossBan)

Wenn du auf Probleme stößt, prüfe die [Issues des Repositories](https://github.com/The-LukeZ/CrossBan/issues) oder Logs für weitere Details. Viel Erfolg beim Hosten!

[^1]: Ein „VPS“ ist ein virtueller Server. Ein VPS ist wie das Mieten einer Wohnung in einem großen Gebäude. Du teilst den physischen Server mit anderen, aber du bekommst deinen eigenen privaten Bereich mit dedizierten Ressourcen, im Gegensatz zu Shared Hosting.\
    Es ist so, als würdest du garantierten Platz, Strom und Privatsphäre erhalten, während andere Mieter (andere VPS-Nutzer) im selben Gebäude wohnen und die Infrastruktur teilen, aber deine Wohnung getrennt ist, sodass du sie so einrichten kannst, wie du möchtest.

[^2]: Ein Docker-Image ist wie ein Bauplan zum Hausbauen.\
    Das gebaute Haus kann dann genutzt werden. Ein gebauter Docker-Container ist wie ein gebautes Haus.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://crossban.thelukez.com/de/dokumentation/self-hosting-a-discord-bot-on-a-vps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
