Systemvoraussetzungen

heinzelhaus läuft auf einem Server, den Ihre Verwaltung oder Ihr IT-Dienstleister betreibt. Auf den Rechnern Ihrer Mitarbeitenden wird nichts installiert: Sie öffnen heinzelhaus im Webbrowser. Diese Seite ist die Checkliste für die Person, die den Server einrichtet.

Damit die Installation beim ersten Anlauf gelingt, prüfen Sie vorher, ob Server, Netzwerk und Zugang passen.

Sie brauchen: root-Zugang zum Server oder zum Proxmox-Host. Die Installation selbst beschreibt die Seite Installation.

Kurz gesagt

Was	Voraussetzung
Betriebssystem	Debian oder Ubuntu. Für Proxmox legt das mitgelieferte Skript einen Container mit Debian 12 an.
Betriebsform	Eigener Server, Proxmox-Container (LXC), virtuelle Maschine oder Server eines Cloud-Anbieters
Zugriff	root, oder ein Benutzer, der mit sudo arbeiten darf
Software	Docker mit Compose-Plugin, git und openssl
Hardware	Als Richtwert 2 Prozessorkerne, 4 GB Arbeitsspeicher und 20 GB Platte. Eine verbindliche Mindestausstattung ist noch nicht festgelegt.
Netzwerk	Internetzugang bei Installation und Updates. Im lokalen Netz Port 3000, mit Domain die Ports 80 und 443.
Zeitzone	Europe/Berlin (Vorgabe, in der .env änderbar)

Der Server

Wo heinzelhaus laufen kann

heinzelhaus läuft auf einem Server Ihrer Verwaltung oder Ihres IT-Dienstleisters. Möglich sind:

• ein Proxmox-Container (LXC), leichtgewichtig und mit einem Skript in wenigen Minuten angelegt,
• eine virtuelle Maschine oder ein eigener Rechner im Büro,
• ein Server bei einem Cloud-Anbieter. Dort entstehen laufende Kosten des Anbieters.

IT Systeme Flores betreibt Ihren Server nicht und bietet kein Hosting an.

Betriebssystem und Werkzeuge

1. Debian oder Ubuntu. Das Installationsskript ist für Debian und Ubuntu getestet, auch in einem Proxmox-Container mit der Option „nesting“.
2. Docker mit Compose-Plugin. heinzelhaus läuft in mehreren getrennten Teilen, den Containern, die Docker gemeinsam startet. Fehlt Docker, installiert das Installationsskript es aus dem offiziellen Docker-Paketarchiv.
3. git. Mit git holen Sie den Programmstand auf den Server. Das Installationsskript installiert es nicht selbst; das Proxmox-Skript tut es im Container.
4. openssl. Das Installationsskript erzeugt damit die Kennwörter der Installation.

Auf einem frischen Debian oder Ubuntu holen Sie git und openssl so:

apt-get update && apt-get install -y git openssl

Begriffe, kurz erklärt

Ein Container ist ein abgeschlossener Teil von heinzelhaus auf dem Server, zum Beispiel die Datenbank oder der PDF-Dienst. Docker Compose startet alle Container gemeinsam. Die Daten liegen in Volumes, das sind Speicherbereiche von Docker, die ein Neubau der Container überdauern. Weitere Begriffe finden Sie unter Begriffe von A bis Z.

Arbeitsspeicher, Prozessor und Platte

heinzelhaus wird auf Ihrem Server gebaut: Bei der Installation und bei jedem Update entstehen die Container aus dem Programmstand. Das braucht Arbeitsspeicher und Platz. Es gibt dafür bisher keine festgelegte Mindestausstattung, nur diese Anhaltspunkte:

Anhaltspunkt	Wert
Vorgaben des Proxmox-Skripts	2 Prozessorkerne, 4096 MB Arbeitsspeicher, 2048 MB Auslagerungsspeicher (Swap), 20 GB Platte
Kleiner Server	2 GB Arbeitsspeicher gelten als Grenzfall. Die Vorlage docker-compose.override.yml.example zeigt dafür Speichergrenzen für die einzelnen Dienste.
Freier Platz für Updates	Unter 2 GB sperrt die Vorabprüfung das Update, unter 5 GB warnt sie.
Dauer des Bauens	Beim ersten Mal einige Minuten, bei Updates auf kleinen Maschinen bis etwa zehn Minuten
Große PDF	Ein Kontenblatt mit 12.000 Zeilen braucht im PDF-Dienst rund 2,5 GB Arbeitsspeicher. Darüber lehnt heinzelhaus die Ausgabe ab.

Planen Sie die Platte außerdem für Ihre Daten: Datenbank, Dokumente und Anhänge liegen auf dem Server. Auch die Datensicherungen liegen standardmäßig im Datenverzeichnis auf demselben Server, siehe Datensicherung und Wiederherstellung.

TODO

Vor Veröffentlichung klären: Gibt es eine verbindlich empfohlene Mindestausstattung (Arbeitsspeicher, Prozessorkerne, Platte)? Reichen 20 GB Platte für den Bau-Zwischenspeicher, hochgeladene Karthago-Sicherungen von bis zu 1,3 GB und lokale Sicherungen? Welche Prozessorarchitektur ist freigegeben (x86-64, ARM)? In der Entwicklung wurden die Container auf einer ARM-Maschine (aarch64) gebaut; eine ausdrückliche Freigabe fehlt. Für die Karthago-Übernahme verwendet heinzelhaus ein SQL-Server-Abbild von Microsoft, dessen Eignung für ARM nicht geprüft ist.

Netzwerk

Ports

Betrieb	Port	Wofür
Im lokalen Netz per IP-Adresse	3000/TCP	heinzelhaus selbst. Einstellbar mit APP_PORT in der .env.
Mit Domain und https	80/TCP und 443/TCP	Der mitgelieferte Dienst Caddy nimmt die Anfragen entgegen und holt das Zertifikat bei Let’s Encrypt. Let’s Encrypt erreicht den Server nur über diese beiden Ports.
Intern	5432 und 8000	Datenbank und PDF-Dienst. Beide sind nur im Docker-Netz des Servers erreichbar und werden nicht nach außen veröffentlicht.

Für den Betrieb mit Domain zeigt ein DNS-Eintrag (A-Record) der Domain auf den Server.

Gut zu wissen

Über reines http läuft die Anmeldung unverschlüsselt durchs Netz. Im Büronetz ist das eine bewusste Entscheidung, die Sie treffen sollten. Außerhalb des Büronetzes brauchen Sie https. Passkeys setzen ebenfalls https und eine Domain voraus, siehe Anmeldesicherheit und Zwei-Faktor-Pflicht.

Ausgehende Verbindungen

Bei Installation und Updates lädt der Server Programmteile aus dem Internet. Geben Sie dafür in der Firewall frei:

Wofür	Ziel
Docker selbst (nur wenn es fehlt)	Docker-Paketarchiv, download.docker.com
Programmstand	git.it-flores.de
Fertige Abbilder der Container	Docker Hub (unter anderem postgres, node, python, caddy, alpine, docker)
Zusätzliche Pakete beim Bauen	Paketquellen von Alpine und Debian, npm und PyPI
Zertifikat (nur mit Domain)	Let’s Encrypt
E-Mail-Versand	Ihr SMTP-Server oder Microsoft 365, siehe Mailversand
Datenübernahme (nur dann)	Microsoft Container Registry für Karthago (SQL Server) und Docker Hub für PowerHaus (Firebird)

Die Schriften der Oberfläche liefert heinzelhaus selbst aus. Es lädt sie nicht von Google-Servern.

Zusätzlich für die Datenübernahme

Die Datenübernahme aus Karthago oder PowerHaus startet bei Bedarf einen eigenen Hilfsdienst auf dem Server (SQL Server für Karthago, Firebird für PowerHaus). Er läuft nur während der Übernahme. Wie die Übernahme in der Oberfläche abläuft, steht unter Überblick und Ablauf.

Für Ihre IT heißt das:

• Arbeitsspeicher. SQL Server braucht allein rund 2 GB. Er ist auf 1200 MB begrenzt (Einstellung MSSQL_MEMORY_LIMIT_MB), damit auf einem Server mit 2 GB noch Luft bleibt.
• Auslagerungsspeicher. Das Skript scripts/migration-auf-server.sh verlangt mindestens 6000 MB Swap und nennt sonst die Befehle, um eine Auslagerungsdatei von 8 GB anzulegen.
• Platz. Hochgeladene Karthago-Sicherungen sind bis zu 1,3 GB groß. Die wiederhergestellten Datenbanken brauchen ein Vielfaches der Sicherungsdateien.
• Der Updater-Dienst muss laufen. Er startet den Hilfsdienst.
• Kennwörter. MSSQL_SA_PASSWORD und FIREBIRD_PASSWORD stehen in der .env. Das Installationsskript erzeugt sie zufällig. SQL Server übernimmt sein Kennwort nur beim ersten Start. Ändern Sie es später in der .env, passt es nicht mehr.

Auf Servern mit wenig Arbeitsspeicher bereiten Sie die Karthago-Übernahme mit dem Skript vor:

1. Rufen Sie im Projektordner ./scripts/migration-auf-server.sh start auf. Das Skript hält Anwendung, Hintergrunddienst und PDF-Dienst an und startet den Import-Datenbankserver.
2. Warten Sie etwa eine Minute. Starten Sie dann die Anwendung mit docker compose up -d app und die Übernahme in heinzelhaus.
3. Rufen Sie nach der Übernahme ./scripts/migration-auf-server.sh ende auf. Das Skript beendet den Import-Datenbankserver, fragt, ob die wiederhergestellten SQL-Server-Datenbanken gelöscht werden sollen, und startet die angehaltenen Dienste wieder.

Gut zu wissen

Hintergrunddienst und PDF-Dienst bleiben bis zum Aufruf von ende angehalten. In dieser Zeit laufen keine Fristen-Erinnerungen und keine geplanten Sicherungen, und PDF-Ausgaben sind nicht möglich. Planen Sie die Karthago-Übernahme deshalb außerhalb der Arbeitszeit.

Die Meldungen, die bei knappen Ressourcen in der Oberfläche erscheinen, und was sie für den Server bedeuten:

Meldung	Was zu tun ist
„Auf dem Server ist zu wenig Platz, um die Sicherung wiederherzustellen.“	Schaffen Sie Platz im Docker-Speicher oder erweitern Sie die Platte.
„Der Arbeitsspeicher reicht für die Wiederherstellung nicht aus.“	Vergrößern Sie den Auslagerungsspeicher oder führen Sie die Übernahme auf einer stärkeren Maschine aus.
„Zeitüberschreitung beim Import-Datenbankserver.“	Bei knappem Arbeitsspeicher dauert das Wiederherstellen sehr lange. Vergrößern Sie den Auslagerungsspeicher.
„Anmeldung am Import-Datenbankserver abgelehnt.“	MSSQL_SA_PASSWORD in der .env passt nicht zum Kennwort, mit dem SQL Server zum ersten Mal gestartet wurde.
„Der Import-Datenbankserver ließ sich nicht starten.“	Läuft der Updater-Dienst? Ist genug Arbeitsspeicher frei? Auf kleinen Servern hilft das Skript scripts/migration-auf-server.sh start.

Weiter geht es hier

• Installation: Das Installationsskript und die Installation auf Proxmox.
• Erste Einrichtung: Der erste Aufruf im Browser.
• Updates: Was ein Update an Platz und Zeit braucht.