Habitica selbst hosten: Deine To-dos als Rollenspiel auf Proxmox

Habitica verwandelt deine Aufgaben in ein Rollenspiel. Erledigst du ein To-do, bekommt dein Charakter Erfahrung und Gold. Vergisst du eine tägliche Aufgabe, verliert er Lebenspunkte. Mit Freunden gründest du eine Party und kämpft gemeinsam gegen Bosse. In diesem Guide hostest du Habitica selbst in einem LXC auf Proxmox, verbindest die Handy-Apps mit deinem Server und richtest Backups ein.

Kurz erklärt

• Habitica kennt drei Arten von Aufgaben: Habits (Gewohnheiten, die du beliebig oft abhakst), Dailies (wiederkehrende Aufgaben) und To-dos (einmalige Aufgaben).
• Mit Freunden bildest du eine Party. Verpasst einer seine Dailies, bekommt bei einem Boss-Quest die ganze Gruppe Schaden. Das motiviert erstaunlich gut.
• Der Code ist Open Source. Eine offizielle Anleitung für den Produktivbetrieb gibt es aber nicht, nur eine für die lokale Entwicklung.
• Gedacht für alle, die Habitica im Heimnetz mit Familie oder Freunden nutzen wollen und ihre Daten lieber selbst halten.
• Du brauchst einen Proxmox-Host und etwas Geduld mit Node.js.

Was du vorher wissen solltest

Self-Hosting ist bei Habitica kein offiziell unterstützter Weg. Das Wiki im GitHub-Repo beschreibt auf der Seite Setting Up Habitica for Local Development, wie Entwickler Habitica lokal starten. Auf diesem Weg baut dieser Guide auf. Die Schritte zum gebauten Client und zum systemd-Service sind meine eigene Ergänzung für den Dauerbetrieb und stehen so nicht im Wiki. Habitica läuft dabei im Entwicklungsmodus (NODE_ENV steht auf development). Es gibt keine fertigen Release-Images und keinen Support für eigene Server. Für dich und ein paar Freunde im Heimnetz reicht das, als öffentlicher Dienst im Internet taugt diese Installation nicht.

Ich habe meine beiden Instanzen ursprünglich mit dem Habitica-Script der Proxmox VE Helper-Scripts installiert. Dieses Script wurde im November 2025 aus der Sammlung entfernt. Die Begründung der Maintainer: Es ging fast mit jedem Habitica-Release kaputt und der Pflegeaufwand war zu hoch. Deshalb zeige ich dir hier die manuelle Installation nach dem offiziellen Wiki. Bei mir laufen zwei Instanzen mit Habitica 5.41.2 in Debian-12-LXCs mit je 2 Kernen und 4 GB RAM. Im Leerlauf belegen sie etwa 600 MB RAM.

Das brauchst du

• Einen Proxmox-VE-Host.
• Einen Debian-12-LXC mit 2 Kernen, 4 GB RAM und mindestens 16 GB Disk. Meine Instanzen laufen noch mit 8 GB und sind schon zu 60 % voll, allein node_modules und der Client-Build brauchen viel Platz. Mit 16 GB hast du Luft für Updates und Backups.
• Im LXC aktiviertes Nesting, weil die Datenbank MongoDB in einem Docker-Container läuft.
• Einen x86-64-Host (amd64). Das libssl-Paket unten gibt es nur für amd64, und MongoDB 7 braucht eine CPU mit AVX-Unterstützung. Aktuelle Mini-PCs haben das.
• Optional einen Reverse Proxy oder Tailscale, wenn du per HTTPS oder von unterwegs zugreifen willst.

Schritt 1: Den LXC anlegen

Lege in der Proxmox-Oberfläche über Create CT einen unprivilegierten Container mit einem Debian-12-Template an. Danach aktivierst du unter Options und Features die Optionen nesting und keyctl. Das brauchst du für Docker im LXC. Gib dem Container eine feste IP, zum Beispiel 192.168.1.x, per DHCP-Reservierung im Router. Stell unter Resources außerdem gleich den Swap auf mindestens 4096 MB. Das Wiki empfiehlt mindestens 4 GB Swap, weil npm i und der Client-Build sonst mit zu wenig RAM abbrechen können. Alle folgenden Befehle führst du als root in der Konsole des Containers aus.

Schritt 2: Pakete, Docker und Node.js installieren

Öffne die Konsole des Containers. Zuerst kommen die Build-Pakete, die das Wiki nennt, plus openssl und nano für die Konfiguration. Docker installierst du über das offizielle Installationsscript, es bringt auch das Compose-Plugin mit:

apt update
apt install -y curl git libkrb5-dev make g++ openssl nano
curl -fsSL https://get.docker.com | sh
docker compose version

Das Wiki installiert zusätzlich das ältere Paket libssl1.1 aus dem Ubuntu-Archiv. Debian 12 bringt es nicht mehr mit, deshalb holst du es per Hand. Das Wiki lädt die Datei über unverschlüsseltes http, hier nimmst du dieselbe Adresse mit https:

cd /tmp
curl -fsSLO https://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb

Habitica verlangt Node.js 20, das steht so in der Datei .nvmrc und in der package.json des Repos. Das Wiki empfiehlt dafür nvm, einen kleinen Versionsmanager für Node. Im Wiki steht noch die ältere nvm-Version v0.39.7, der Befehl unten nutzt v0.40.8, zum Zeitpunkt dieses Guides das aktuelle Release laut GitHub. Nach der Installation lädst du die Shell-Konfiguration neu, damit der Befehl nvm verfügbar ist:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
source ~/.bashrc
nvm install 20
nvm alias default 20
node --version
npm --version

node --version sollte mit v20 beginnen, npm --version mit 10. Nimm keine neuere Node-Version, Habitica ist auf Node 20 festgelegt.

Schritt 3: Habitica holen und Abhängigkeiten installieren

Das Wiki klont einfach den Standard-Branch. Der heißt bei Habitica develop und enthält den aktuellen Entwicklungsstand. Für den Dauerbetrieb nimmst du besser den Branch release, der den Stand der letzten Veröffentlichung enthält:

cd /opt
git clone --branch release https://github.com/HabitRPG/habitica
cd habitica
npm i

npm i lädt sehr viele Pakete und baut im Anschluss einige Teile, auch die Abhängigkeiten des Web-Clients. Das dauert einige Minuten. Bricht es mit EPIPE-Fehlern ab oder hält es einfach an, fehlt RAM. Prüfe dann den Swap aus Schritt 1 und starte npm i erneut.

Schritt 4: MongoDB starten

Habitica speichert alles in MongoDB. Das Repo bringt die Compose-Datei docker-compose.mongo-only.yml mit, die nur die Datenbank startet. Das Wiki nutzt sie über npm run docker:mongo:dev, dabei läuft die Datenbank aber im Vordergrund. Mit -d läuft sie im Hintergrund und startet dank restart: unless-stopped nach einem Reboot automatisch:

cd /opt/habitica
docker compose -f docker-compose.mongo-only.yml up -d
docker ps

Der Container heißt habitica-mongodb-only und nutzt das Image mongo:7.0. Ein Healthcheck richtet beim ersten Start das Replica Set ein, das Habitica erwartet. Warte, bis docker ps beim Container (healthy) anzeigt, das kann eine Minute dauern. Die Daten landen im Ordner mongodb-data-docker im Habitica-Verzeichnis. MongoDB lauscht dabei auf Port 27017 auf allen Interfaces des LXC. Lass diesen Port nicht aus dem Heimnetz heraus erreichbar.

Schritt 5: config.json anlegen

Die Konfiguration kopierst du aus der Beispieldatei und erzeugst gleich zwei zufällige Schlüssel:

cd /opt/habitica
cp config.json.example config.json
openssl rand -hex 32
openssl rand -hex 32
nano config.json

In der config.json änderst du diese Einträge:

• BASE_URL: Dort steht http://localhost:3000. Trage die Adresse ein, unter der du Habitica später aufrufst, also zum Beispiel http://192.168.1.x:3000 oder deine Domain hinter dem Reverse Proxy.
• TRUSTED_DOMAINS: Dort steht localhost,https://habitica.com. Hänge deine Adresse mit Komma an, zum Beispiel localhost,https://habitica.com,http://192.168.1.x:3000. Das alte Community-Script hat das genauso gemacht.
• SESSION_SECRET: Hier kommt der erste Wert aus openssl rand -hex 32 rein.
• SESSION_SECRET_KEY: Hier kommt der zweite Wert rein. Habitica nutzt ihn als AES-Schlüssel und erwartet genau 64 Hex-Zeichen. Ein beliebiges Passwort funktioniert an dieser Stelle nicht.

Die Datenbankverbindung in NODE_DB_URI passt bereits zum MongoDB-Container aus Schritt 4. NODE_ENV bleibt auf development. Speichere die Datei, bevor du weitermachst. Der Client-Build im nächsten Schritt liest BASE_URL und TRUSTED_DOMAINS aus der config.json und baut sie fest ein.

Schritt 6: Den Web-Client bauen

Für die Entwicklung startet das Wiki den Web-Client mit einem eigenen Dev-Server auf Port 5173. Für den Dauerbetrieb ist es einfacher, den Client einmal zu bauen. Dann liefert der Habitica-Server die Weboberfläche selbst auf Port 3000 aus. So läuft es bei mir:

cd /opt/habitica
npm run client:build

Der Build landet in website/client/dist. Teste den Server danach einmal im Vordergrund mit npm start. Wenn im Log keine Fehler auftauchen und http://192.168.1.x:3000 im Browser die Startseite zeigt, beendest du ihn mit Strg+C.

Schritt 7: Habitica als systemd-Service starten

Damit Habitica nach einem Neustart von selbst startet, legst du mit nano /etc/systemd/system/habitica.service einen systemd-Service an. Weil Node über nvm installiert ist, lädt der Service nvm vorher:

[Unit]
Description=Habitica
After=docker.service network-online.target
Wants=docker.service network-online.target

[Service]
WorkingDirectory=/opt/habitica
ExecStart=/bin/bash -c 'source /root/.nvm/nvm.sh && npm start'
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now habitica

npm start startet den Server mit node --watch, also so, wie es das Repo für die Entwicklung vorsieht. Das ist der Teil, der diese Installation inoffiziell macht: Der Entwicklungsmodus ist nicht auf Performance und Sicherheit im Internet ausgelegt. Für ein paar Leute im Heimnetz reicht es. Die Logs siehst du mit journalctl -u habitica -f.

Schritt 8: Erste Schritte in Habitica

Öffne http://192.168.1.x:3000 im Browser und registriere dich. Dein Account existiert nur auf deinem Server, ein Account von habitica.com funktioniert hier nicht. Danach legst du deinen Avatar fest und bekommst ein paar Beispielaufgaben.

• Trage zwei oder drei Habits ein, die du fördern willst, zum Beispiel ein Glas Wasser trinken.
• Lege nur wenige Dailies an. Zu viele verpasste Dailies kosten am Tagesende Lebenspunkte und frustrieren schnell.
• Einmalige Dinge wie einen Arzttermin packst du in die To-dos.
• Deine Freunde registrieren sich ebenfalls auf deinem Server. Danach gründest du eine Party und lädst sie per Benutzername ein.

Bedenke, dass sich jeder registrieren kann, der deinen Server erreicht. Mail-Versand ist ohne eigenen SMTP-Server nicht eingerichtet, Passwort-Reset per Mail klappt also nicht. Das ist ein weiterer Grund, die Instanz im Heimnetz oder hinter Tailscale zu lassen.

Schritt 9: Die Handy-Apps mit deinem Server verbinden

Beide offiziellen Apps können inzwischen einen eigenen Server nutzen. Die Einstellung ist versteckt:

• iOS: Seit Version 4.0.3. Melde dich ab und tippe im Login-Screen achtmal auf das Greifen-Logo. Dann tippst du oben rechts auf Production, wechselst auf Custom und trägst deine Server-Adresse ein.
• Android: Die Funktion ist seit Frühjahr 2026 in der Play-Store-Version. Tippe im Login-Screen mehrmals auf das Logo, bis die Meldung Server settings unlocked! erscheint. Danach wählst du Custom Server und gibst die Adresse ein. Wear-OS-Uhren unterstützen eigene Server laut den Entwicklern noch nicht.

Die Android-App erlaubt laut ihrer Netzwerk-Konfiguration auch unverschlüsselte http-Verbindungen. Für den Zugriff von unterwegs nimmst du trotzdem besser HTTPS über einen Reverse Proxy oder verbindest dich per Tailscale. Denk daran, dann auch BASE_URL und TRUSTED_DOMAINS in der config.json anzupassen, den Client mit npm run client:build neu zu bauen und den Service mit systemctl restart habitica neu zu starten.

Schritt 10: Backups

Alle Daten stecken in MongoDB. Die Datenbank heißt laut config.json standardmäßig habitica-dev. Einen Dump ziehst du direkt aus dem Container:

docker exec habitica-mongodb-only mongodump --db habitica-dev --archive > /root/habitica-$(date +%F).archive

Zurückspielen geht mit docker exec -i habitica-mongodb-only mongorestore --drop --archive < /root/habitica-DATUM.archive. Das -i ist dabei wichtig, sonst kommt die Datei nicht im Container an. Stoppe vorher mit systemctl stop habitica den Server. Sichere außerdem deine config.json. Zusätzlich lohnt sich ein regelmäßiges Proxmox-Backup des ganzen LXC auf ein NAS. Damit hast du auch Node, Build und Konfiguration gesichert. Ob ein Backup wirklich funktioniert, weißt du erst, wenn du es einmal zurückgespielt hast.

So prüfst du, ob es läuft

Habitica hat einen Status-Endpoint. Im Container sollte dieser Aufruf eine Antwort mit "success":true und "status":"up" zurückgeben. systemctl status habitica sollte active (running) zeigen und docker ps den MongoDB-Container als (healthy):

curl http://127.0.0.1:3000/api/v3/status
systemctl status habitica
docker ps

Den Status-Endpoint kannst du auch als HTTP-Check in dein Monitoring aufnehmen. Wie ich das mit Benachrichtigung aufs Handy mache, steht in Uptime Kuma und ntfy.

Typische Probleme

• Server startet nicht und meldet Datenbankfehler: Der MongoDB-Container läuft noch nicht oder das Replica Set ist noch nicht initialisiert. Prüfe mit docker ps, ob der Container als healthy gilt.
• Weboberfläche lädt nicht: Du hast npm run client:build vergessen oder nach einer Änderung nicht wiederholt.
• Disk voll: Mit weniger als den empfohlenen 16 GB wird es schnell eng, vor allem bei Updates. Vergrößere die Disk in Proxmox unter Resources.
• MongoDB-Container startet ständig neu: Schau mit docker logs habitica-mongodb-only nach. Meldet MongoDB, dass die CPU kein AVX unterstützt, ist der Host zu alt für mongo:7.0.
• Login klappt, aber die Seite springt zurück oder Weiterleitungen gehen nicht: Prüfe BASE_URL und TRUSTED_DOMAINS in der config.json und baue danach den Client neu.
• Update macht Probleme: Ein Update bedeutet im Ordner /opt/habitica nacheinander git pull, npm i, npm run client:build und systemctl restart habitica. Vergleiche vorher deine config.json mit einer neuen config.json.example, falls neue Einträge dazugekommen sind. Mach vorher einen Snapshot des LXC. Genau an dieser Stelle ist das Community-Script früher immer wieder gescheitert.

Fazit

Habitica selbst zu hosten ist etwas mehr Bastelei als bei vielen anderen Self-Hosting-Projekten, weil es keinen offiziellen Weg für den Dauerbetrieb gibt. Hast du die Instanz einmal am Laufen, ist sie im Alltag aber unauffällig. Mit den Apps auf dem Handy und einer Party aus Freunden oder Familie wird aus der To-do-Liste ein kleines Gruppenspiel. Plane Updates bewusst und mit Snapshot ein, dann hast du lange Ruhe.

Hat dir der Guide geholfen? Dann spendier mir gern einen Kaffee auf Ko-fi. Damit bleibt MappleBox werbefrei.

Weitere Guides

• Plesk Kernel Update: Live-Server nach einem Jahr Uptime patchen
• Proxmox CPU Governor powersave: Fix für 88 °C im Idle am Mini-PC
• Homelab starten 2026: So legst du als Anfänger richtig los