Voraussetzungen#

Hinata läuft bequem auf einem einzelnen, bescheidenen Server und skaliert von dort aus nach oben. Diese Seite listet auf, was der Host braucht, was jede Komponente erwartet und was du zum Bauen aus dem Quellcode benötigst.

Host-Anforderungen#

Der Server und seine Abhängigkeiten werden als Container ausgeliefert, daher braucht der Host hauptsächlich eine Container-Laufzeitumgebung und genug Reserve, um die JVM, MongoDB und MinIO nebeneinander zu betreiben.

• Docker Engine + Docker Compose v2 sind die einzigen harten Software-Voraussetzungen. Die Compose-Dateien verwenden v2-Syntax (docker compose, nicht das veraltete docker-compose).
• Architektur: Images werden für x86_64 und arm64 veröffentlicht, sodass Apple Silicon, AWS Graviton und Raspberry-Pi-artige arm64-Geräte alle funktionieren.

Komponenten-Anforderungen#

Ein produktiver Hinata-Stack ist eine Handvoll zusammenarbeitender Dienste. Hier ist, was jeder einzelne braucht.

Netzwerk#

• Öffentliches DNS + TLS. Für alles über einen lokalen Test hinaus brauchst du öffentliche DNS-Namen und TLS. Terminiere TLS an einem Reverse Proxy und leite über die internen Ports an Hinata weiter. Typische Namen sind api.track.example.com (API) und track.example.com (Web-App).
• Interne Ports. Der Server veröffentlicht standardmäßig 3356 und der Web-/App-Container 3456 (HINATA_PORT / HINATA_APP_PORT). Das sind die Ports, an die dein Proxy weiterleitet; sie sollten nicht direkt dem Internet ausgesetzt werden.
• Vertrauenswürdige Proxies. Setze HINATA_TRUSTED_PROXIES auf die CIDRs deiner Reverse Proxies, damit X-Forwarded-For nur von diesen berücksichtigt wird. Leer bedeutet, keinem zu vertrauen.
• CORS. Die gehostete Web-App ruft die API cross-origin auf, liste daher deine Browser-Origins in HINATA_CORS_ALLOWED_ORIGINS auf.

MongoDB-Replikatset#

Produktives Hinata erwartet ein Replikatset, kein eigenständiges MongoDB, aus zwei Gründen: Es ist für die transaktionalen Garantien erforderlich, auf die sich Hinata stützt, und es ermöglicht einen sicheren rollierenden Betrieb. Das mitgelieferte Compose bringt 2 Datenknoten + 1 Arbiter mit TLS und X.509-Client-Authentifizierung hoch. Die App authentifiziert sich gegenüber MongoDB mit einem X.509-Zertifikat — nicht mit dem SCRAM-Root-Passwort, das für interne/administrative Zwecke reserviert ist.

• Erzeuge das Cluster-Keyfile mit ./deploy/generate-secrets.sh.
• Erzeuge die Produktiv-PKI mit ./deploy/x509/generate-certs.sh prod, lege dann den X.509-Benutzer mit ./deploy/x509/init-prod-user.sh an.

Vollständige Details findest du unter MongoDB & X.509.

S3 / MinIO#

Hinata braucht einen S3-kompatiblen Objektspeicher. Das gebündelte MinIO ist der einfache Standard (Bucket HINATA_S3_BUCKET, Standard hinata), konfiguriert mit MINIO_ROOT_USER / MINIO_ROOT_PASSWORD; in Dev werden zusätzlich HINATA_S3_ACCESS_KEY / HINATA_S3_SECRET_KEY verwendet. Du kannst Hinata stattdessen auch auf jeden externen S3-kompatiblen Anbieter ausrichten. Siehe Objektspeicher.

SMTP#

Für echte Mail — E-Mail-Verifizierung, Benachrichtigungen und Passwort-Reset — konfiguriere ein ausgehendes SMTP-Relay mit HINATA_SMTP_HOST/PORT/USERNAME/PASSWORD/AUTH/STARTTLS und einer sinnvollen HINATA_MAIL_FROM. In der Entwicklung fängt Mailpit alles unter http://localhost:8025 ab, sodass nichts die Maschine verlässt. Siehe E-Mail & SMTP.

Hinata Connect Gateway (optional)#

Push-Benachrichtigungen und Universal Links fließen durch das Connect Gateway. Die Nutzung des gehosteten Gateways bedeutet, dass Selbst-Hoster kein eigenes Firebase-Projekt benötigen — der Server registriert sich selbst beim Start. Es ist optional; du kannst ohne Push betreiben oder dein eigenes Gateway aufsetzen und HINATA_GATEWAY_BASE_URL setzen. Siehe Hinata Connect Gateway.

Client-Anforderungen#

Die App läuft auf:

• Android- und iOS-Smartphones/Tablets,
• Web (jeder moderne Browser),
• macOS-Desktop.

Weil die App mehrserverfähig ist, brauchen Nutzer nur die URL eines laufenden Servers; keine benutzerbezogene Installationskonfiguration ist erforderlich.

Entwicklungsvoraussetzungen#

Das Bauen aus dem Quellcode (statt Images zu ziehen) erfordert die Toolchains hinter jedem Repository:

• hinata-server — JDK 21 und der gebündelte Gradle-Wrapper (./gradlew). Bringe die Entwicklungsabhängigkeiten mit docker compose -f docker-compose.dev.yml up -d hoch (Mongo-Replikatset, Mailpit, MinIO) und starte dann den Server:

bash docker compose -f docker-compose.dev.yml up -d # Mongo RS, Mailpit, MinIO HINATA_MONGODB_URI="mongodb://localhost:27017/hinata?replicaSet=rs0&directConnection=true" \ HINATA_S3_ACCESS_KEY=hinata HINATA_S3_SECRET_KEY=hinata-dev-secret \ ./gradlew bootRun

Führe die Testsuite mit ./gradlew build aus.

• hinata-app — ein Flutter-SDK (mit den Android-/iOS-/macOS-Toolchains für die Ziele, die du baust). State über bloc/cubit, Routing über go_router, i18n über i18next.

Nächste Schritte#

• Schnellstart — drei Befehle zu einem laufenden Stack.
• Produktiv-Deployment — der vollständige Produktiv-Weg.
• Reverse Proxy & TLS — öffentliches DNS, Zertifikate und Weiterleitung.