Appwrite 1.9 mit MongoDB im Homelab: Dein Self-Hosted Backend

Appwrite 1.9 mit MongoDB im Homelab: Dein Self-Hosted Backend

Moin, liebe smoth.me Community!

Als erfahrener Admin und Heimlabor-Enthusiast habe ich in den letzten Jahren so einige Backend-Lösungen ausprobiert, sei es für kleine persönliche Projekte, Smart-Home-Integrationen oder auch mal einen Proof-of-Concept für die Arbeit. Wenn es darum geht, schnell und effizient eine solide API, Authentifizierung, Datenbank und Dateispeicher zu haben, ohne alles von Grund auf neu zu schreiben, ist mir Appwrite immer wieder positiv aufgefallen. Es ist quasi ein Open-Source-Firebase für dein eigenes System – und das ist für uns Homelab-Admins natürlich Gold wert.

Die Version 1.9 hat jetzt ein Feature an Bord, das ich persönlich schon lange erwartet habe und das viele von euch sicher freuen wird: nativen MongoDB-Support. Das ist nicht nur eine technische Neuerung, sondern eröffnet auch ganz neue Möglichkeiten, gerade wenn du bereits mit NoSQL-Datenbanken arbeitest oder die Flexibilität von MongoDB schätzt. In diesem Guide zeige ich dir, wie du Appwrite 1.9 mit MongoDB in deinem Homelab aufsetzt, welche Vorteile das bringt und worauf du achten solltest.

Was ist Appwrite eigentlich?

Für diejenigen, die Appwrite noch nicht kennen: Stell es dir als eine Suite von Backend-Services vor, die du in deinem eigenen Rechenzentrum (oder eben auf deinem Homelab-Server) betreiben kannst. Es bietet dir out-of-the-box:

• Datenbanken: Für die Speicherung deiner Anwendungsdaten. Bisher primär MariaDB/PostgreSQL, jetzt eben auch MongoDB.
• Authentifizierung: Benutzerverwaltung, OAuth (Google, GitHub etc.), E-Mail-Verifizierung – alles dabei.
• Speicher (Storage): Für Dateien, Bilder, Videos, die deine Anwendung benötigt.
• Funktionen (Functions): Serverlose Funktionen, die auf bestimmte Ereignisse reagieren (z.B. nach dem Speichern eines Dokuments).
• Realtime: Echtzeit-Updates für deine Clients, wenn sich Daten ändern.
• Messaging: E-Mail und SMS-Integration.

Kurz gesagt: Es nimmt dir einen Großteil der mühsamen Backend-Entwicklung ab, sodass du dich auf die Logik deiner Anwendung konzentrieren kannst. Und das Beste: Du behältst die volle Kontrolle über deine Daten.

Warum Appwrite 1.9 mit MongoDB ein Game Changer ist

Die Heise-Meldung hat es schon kurz angerissen: Appwrite 1.9 bringt MongoDB-Support. Aber was bedeutet das konkret für uns Heimlaboranten?

MongoDB als neue Datenbank-Option

Bisher setzte Appwrite standardmäßig auf relationale Datenbanken wie MariaDB oder PostgreSQL. Das ist super und bewährt. Aber in vielen modernen Anwendungen, gerade wenn es um flexible Schemata, große Datenmengen oder dokumentenorientierte Daten geht, spielt MongoDB seine Stärken aus. Persönlich nutze ich MongoDB schon länger für Projekte, bei denen ich nicht von Anfang an ein starres Schema festlegen will oder muss. Die Möglichkeit, Appwrite jetzt direkt mit MongoDB zu betreiben, vereinfacht die Architektur erheblich, wenn du sowieso schon ein NoSQL-Mindset hast oder deine Daten besser in Dokumentenstrukturen abbilden kannst.

Mein Tipp: Überlege dir gut, ob MongoDB für dein Projekt passt. Wenn du stark strukturierte, transaktionsintensive Daten hast, ist eine relationale DB vielleicht immer noch die bessere Wahl. Für Projekte mit variablen Datenstrukturen oder schnellen Iterationen ist MongoDB oft unschlagbar.

Ressourcenzentrierte API-Keys und Realtime-Filter

Das ist ein Detail, das für die Sicherheit und Performance deiner Anwendungen im Homelab wichtig ist. Mit ressourcenzentrierten API-Keys kannst du die Berechtigungen viel feiner granulieren. Statt einem API-Key, der Zugriff auf alles hat, kannst du jetzt Keys erstellen, die nur auf bestimmte Ressourcen zugreifen dürfen. Das minimiert das Risiko, falls mal ein Key kompromittiert wird. Die Query-Filter für Realtime-Subscriptions sind ebenfalls genial: Du kannst jetzt noch präziser festlegen, welche Datenänderungen deine Clients in Echtzeit erhalten sollen. Das reduziert den Netzwerk-Traffic und die Last auf deinem Server, was besonders in einem Homelab mit begrenzten Ressourcen ins Gewicht fällt.

Performance-Verbesserungen

Jede neue Version bringt in der Regel Performance-Optimierungen mit sich. Auch wenn die genauen Details in der Quelle nicht genannt werden, ist es eine willkommene Ergänzung. Gerade bei selbst gehosteten Diensten zählt jede Optimierung, um die Ressourcen deines Servers effizient zu nutzen. In meiner Erfahrung merkt man diese kleinen Verbesserungen oft erst unter Last, aber sie zahlen sich langfristig aus.

Voraussetzungen für dein Appwrite-Homelab

Bevor wir loslegen, stellen wir sicher, dass dein Server bereit ist. Ich gehe davon aus, dass du einen Linux-Server (z.B. Ubuntu, Debian) am Laufen hast. Für mich persönlich ist Ubuntu Server LTS immer eine gute Wahl, da es stabil und gut dokumentiert ist.

Hardware-Anforderungen

• RAM: Mindestens 2 GB, besser 4 GB oder mehr. Appwrite selbst, Docker und MongoDB brauchen ihren Arbeitsspeicher. Wenn du noch andere Dienste auf dem Server betreibst, plane entsprechend mehr ein.
• CPU: Ein moderner Dual-Core-Prozessor ist das Minimum. Vier Kerne oder mehr sind natürlich besser für Performance und Skalierbarkeit.
• Speicher: Mindestens 20 GB freier Speicherplatz. Plane großzügig, besonders wenn du den Storage-Service von Appwrite intensiv nutzen willst. Eine SSD ist hier klar von Vorteil.

Software-Anforderungen

• Linux-Betriebssystem: Eine aktuelle Distribution (z.B. Ubuntu 22.04 LTS, Debian 11/12).
• Docker: Die Container-Engine muss installiert und lauffähig sein.
• Docker Compose: Wird für die Orchestrierung der Appwrite-Dienste benötigt.
• Grundkenntnisse: Vertrautheit mit der Linux-Kommandozeile und grundlegenden Netzwerkkonzepten ist hilfreich.

Netzwerk-Vorbereitung (optional, aber empfohlen)

• Portfreigaben: Standardmäßig läuft Appwrite auf Port 80 (HTTP) und 443 (HTTPS). Stelle sicher, dass diese Ports auf deinem Server erreichbar sind, falls du von außen zugreifen möchtest. Denk an deine Firewall (UFW)!
• DNS-Eintrag: Für eine saubere Konfiguration und die Nutzung von Let's Encrypt für HTTPS empfehle ich, einen DNS-Eintrag (z.B. appwrite.dein-homelab.de) auf die IP-Adresse deines Servers zu legen.

Schritt-für-Schritt: Appwrite 1.9 mit Docker Compose einrichten

Jetzt wird's ernst! Wir installieren Appwrite mit Docker Compose und konfigurieren es für MongoDB.

1. Server vorbereiten und Docker installieren

Zuerst aktualisieren wir den Server und stellen sicher, dass Docker und Docker Compose installiert sind. Wenn du Docker schon hast, kannst du diesen Schritt überspringen.

Verbinde dich per SSH mit deinem Server:

ssh dein_user@deine_server_ip

System aktualisieren:

sudo apt update && sudo apt upgrade -y

Docker installieren (falls noch nicht geschehen):

sudo apt install ca-certificates curl gnupg lsb-release -y
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Füge deinen Benutzer der Docker-Gruppe hinzu, damit du Docker-Befehle ohne sudo ausführen kannst. Danach musst du dich einmal ab- und wieder anmelden oder den Server neu starten.

sudo usermod -aG docker $USER

2. Appwrite-Installationsskript und Konfiguration für MongoDB

Appwrite bietet ein praktisches Installationsskript, das die docker-compose.yml und die .env-Datei für dich generiert. Wir nutzen das, passen es aber direkt für MongoDB an.

Erstelle ein Verzeichnis für Appwrite:

mkdir appwrite && cd appwrite

Lade das Installationsskript herunter und führe es aus. Wähle beim Ausführen Linux als Betriebssystem.

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)":/appwrite \
    appwrite/appwrite:1.9.0 setup

Während der Installation wirst du nach einigen Parametern gefragt. Gib die gewünschten Hostnamen und Ports an. Für den Appwrite secret key kannst du einfach Enter drücken, es wird ein zufälliger generiert.

Nachdem das Skript gelaufen ist, findest du im Verzeichnis appwrite eine docker-compose.yml und eine .env-Datei. Jetzt kommt der wichtige Teil für MongoDB.

Öffne die docker-compose.yml mit deinem Lieblingseditor (z.B. nano):

nano docker-compose.yml

Suche nach dem db-Service. Standardmäßig wird hier MariaDB verwendet. Du wirst einen Abschnitt für mariadb und einen auskommentierten Abschnitt für mongodb finden. Kommentiere den mariadb-Service und den dazugehörigen Volume-Eintrag aus. Entkommentiere den mongodb-Service und den dazugehörigen Volume-Eintrag. Es sollte dann ungefähr so aussehen (ich zeige nur die relevanten Teile):

# docker-compose.yml (Auszug)
services:
  # ... andere Dienste ...

  db:
    # image: mariadb:10.7
    # hostname: mariadb
    # restart: always
    # ... weitere mariadb configs ...
    # volumes:
    #   - ${APPWRITE_DATA_PATH}/mariadb:/var/lib/mysql

    image: mongo:6.0 # oder eine andere 6.x Version, siehe Appwrite Doku
    hostname: mongodb
    restart: always
    environment:
      - MONGO_INITDB_ROOT_USERNAME=${_APP_DB_USER}
      - MONGO_INITDB_ROOT_PASSWORD=${_APP_DB_PASS}
    volumes:
      - ${APPWRITE_DATA_PATH}/mongodb:/data/db
    healthcheck:
      test: test $$(echo "db.runCommand('ping').ok" | mongosh -u $${MONGO_INITDB_ROOT_USERNAME} -p $${MONGO_INITDB_ROOT_PASSWORD} --authenticationDatabase admin --quiet) -eq 1
      interval: 10s
      timeout: 5s
      retries: 5

  # ... weitere Dienste ...

Wichtig zu wissen: Die Variablen wie ${_APP_DB_USER} und ${_APP_DB_PASS} kommen aus deiner .env-Datei. Appwrite ist clever genug, diese für die MongoDB-Initialisierung zu nutzen.

Speichere die docker-compose.yml ab (Strg+X, Y, Enter bei nano).

Nun bearbeiten wir die .env-Datei:

nano .env

Suche nach der Zeile _APP_DB_ADAPTER. Ändere sie von mariadb (oder was auch immer dort steht) zu mongodb. Stelle außerdem sicher, dass die Datenbank-Host und Port-Variablen korrekt sind, falls du den Hostnamen des MongoDB-Containers geändert hast (was wir hier nicht tun, da wir den Service einfach db nennen und dieser dann auf mongodb als Hostname intern auflöst):

# .env (Auszug)
# ...
_APP_DB_ADAPTER="mongodb"
_APP_DB_HOST="mongodb" # Dies ist der Hostname des MongoDB-Containers im Docker-Netzwerk
_APP_DB_PORT="27017" # Standard-Port für MongoDB

# ...
# Stelle sicher, dass _APP_DB_USER und _APP_DB_PASS gesetzt sind
_APP_DB_USER="your_db_user" # Wird vom Setup-Skript gesetzt, anpassen falls gewünscht
_APP_DB_PASS="your_db_password" # Wird vom Setup-Skript gesetzt, anpassen falls gewünscht
# ...

Mein Tipp: Überprüfe die Werte für _APP_DB_USER und _APP_DB_PASS. Appwrite generiert diese beim ersten Setup, aber es ist gut, sie zu kennen und bei Bedarf zu ändern. Diese werden für den Root-Benutzer der MongoDB-Instanz verwendet.

Speichere die .env-Datei ab.

3. Appwrite starten und konfigurieren

Jetzt starten wir Appwrite mit der neuen Konfiguration:

docker compose up -d

Dieser Befehl lädt die benötigten Docker-Images herunter (einschließlich MongoDB), erstellt die Container und startet sie im Hintergrund. Das kann beim ersten Mal etwas dauern.

Du kannst den Status der Container überprüfen mit:

docker compose ps

Und die Logs, falls etwas schiefgeht:

docker compose logs

Sobald alle Container laufen (insbesondere appwrite-db, der jetzt MongoDB ist, und appwrite-app), solltest du auf das Appwrite-Dashboard zugreifen können.

Öffne deinen Webbrowser und navigiere zu der IP-Adresse oder dem Hostnamen deines Servers (z.B. http://deine_server_ip oder https://appwrite.dein-homelab.de).

Du wirst aufgefordert, ein Admin-Konto zu erstellen. Wähle einen starken Benutzernamen und ein sicheres Passwort. Dies sind die Zugangsdaten für dein Appwrite-Dashboard.

4. Erste Schritte im Appwrite-Dashboard

Nach der Anmeldung im Dashboard kannst du dein erstes Projekt erstellen. Gib ihm einen Namen, z.B. "Mein Super Projekt".

Innerhalb deines Projekts kannst du dann die verschiedenen Appwrite-Dienste nutzen:

• Databases: Hier siehst du jetzt, dass MongoDB als Backend verwendet wird. Du kannst Collections erstellen, Dokumente hinzufügen und Queries ausführen.
• Auth: Benutzerregistrierung und -verwaltung.
• Storage: Dateien hochladen und verwalten.
• Functions: Serverlose Funktionen definieren.

Wichtig: Wenn du mit MongoDB arbeitest, wirst du die Flexibilität der schemalosen Collections schätzen. Du musst kein starres Schema definieren, bevor du Dokumente einfügst. Appwrite abstrahiert das aber teilweise, sodass es sich auf den ersten Blick ähnlich anfühlt wie bei relationalen Datenbanken. Die eigentlichen Vorteile kommen zum Tragen, wenn du über die API direkt mit den Daten interagierst.

Häufige Fehler und Lösungen

In meiner Erfahrung gibt es ein paar Stolpersteine, über die man beim Setup von Appwrite (oder eigentlich jedem Docker-basierten Dienst) immer wieder stolpert.

1. Port-Konflikte

Problem: Du kannst nicht auf das Appwrite-Dashboard zugreifen, oder die Ports 80/443 sind bereits belegt.

Lösung:

• Überprüfe, ob andere Dienste auf deinem Server die Ports 80 oder 443 nutzen (z.B. Nginx, Apache).
• Du kannst die externen Ports in der docker-compose.yml anpassen, wenn du Appwrite nicht auf den Standard-Webports betreiben möchtest (z.B. "8080:80"). Denk aber daran, dass du dann auch einen Reverse Proxy wie Nginx oder Traefik davor schalten müsstest, um HTTPS und den Standard-Port 443 zu nutzen.
• Kontrolliere deine Firewall (UFW). Stelle sicher, dass Ports 80 und 443 (oder deine benutzerdefinierten Ports) erlaubt sind:

  sudo ufw allow 80/tcp
  sudo ufw allow 443/tcp
  sudo ufw reload

2. `.env` Datei falsch konfiguriert (insbesondere DB-Adapter)

Problem: Appwrite startet nicht richtig, oder du siehst Fehlermeldungen bezüglich der Datenbankverbindung in den Logs (docker compose logs).

Lösung:

• Stelle sicher, dass _APP_DB_ADAPTER="mongodb" in deiner .env-Datei korrekt gesetzt ist.
• Überprüfe, ob der db-Service in deiner docker-compose.yml wirklich auf das mongo-Image und die korrekten Volumes verweist und der mariadb-Teil auskommentiert ist.
• Manchmal hilft es, die Container komplett zu löschen und neu zu starten, wenn du die Datenbankkonfiguration grundlegend geändert hast (Vorsicht: Datenverlust, wenn du keine Volumes gesichert hast!):

  docker compose down -v
  docker compose up -d

  Der -v Parameter löscht auch die Volumes, was bei einer frischen Installation gewünscht ist, um die Datenbank neu zu initialisieren.

3. Docker-Berechtigungen

Problem: Du kannst docker compose Befehle nicht ohne sudo ausführen.

Lösung:

• Stelle sicher, dass dein Benutzer zur docker-Gruppe hinzugefügt wurde:

  sudo usermod -aG docker $USER

• Danach ist es wichtig, dass du dich einmal von deiner SSH-Sitzung abmeldest und neu anmeldest (oder den Server neu startest), damit die Gruppenmitgliedschaft wirksam wird.

Fazit und Nächste Schritte

Glückwunsch! Du hast Appwrite 1.9 mit MongoDB erfolgreich in deinem Homelab eingerichtet. Mit dieser Kombination hast du ein leistungsstarkes und flexibles Backend für all deine Projekte zur Hand. Die Integration von MongoDB ist ein echter Schritt nach vorne und bietet dir mehr Wahlfreiheit bei der Datenmodellierung.

Für mich persönlich ist Appwrite ein unverzichtbares Tool im Homelab geworden, um schnell Prototypen zu bauen oder Smart-Home-Daten zu speichern und zu verarbeiten. Die Version 1.9 mit MongoDB macht es noch attraktiver.

Was sind die nächsten Schritte? Nun, das hängt ganz von deinen Projekten ab:

• Client-SDKs erkunden: Appwrite bietet SDKs für viele Sprachen (Web, Mobile, Backend). Tauche ein und beginne, deine Anwendungen zu bauen.
• Funktionen nutzen: Experimentiere mit den Appwrite Functions, um serverseitige Logik zu implementieren, z.B. um Daten bei der Speicherung zu validieren oder externe APIs anzusprechen.
• Realtime-APIs: Baue eine Echtzeit-Anwendung, die von den Query-Filtern in 1.9 profitiert.
• Automatisierung mit n8n: Wenn du, wie ich, ein Fan von n8n bist, kannst du Appwrite hervorragend als Datenquelle oder Ziel für deine Workflows nutzen. Denk an Automatisierungen, die auf Appwrite-Ereignisse reagieren oder Daten in Appwrite schreiben.
• Sicherheit härten: Wenn dein Appwrite von außen erreichbar ist, solltest du über einen Reverse Proxy mit Let's Encrypt für HTTPS nachdenken und die Zugriffsberechtigungen im Dashboard genau prüfen.

Ich hoffe, dieser Guide hilft dir, Appwrite in deinem Homelab optimal zu nutzen. Viel Spaß beim Experimentieren und Bauen!