Erste Einrichtung

Nach der Installation öffnen Sie die Adresse Ihrer heinzelhaus-Installation im Browser. Solange noch kein Benutzer existiert, führt die Anmeldeseite von selbst zur Seite „Ersteinrichtung“. Sie trägt die Überschrift „heinzelhaus einrichten“ und fragt: „Ist das eine neue Verwaltung oder ein neu aufgesetzter Server?“

Damit Ihre Installation die Angaben Ihrer Verwaltung kennt und es ein Administratorkonto gibt, mit dem Sie Ihr Team einladen können. Oder damit ein neu aufgesetzter Server den Datenbestand eines alten bekommt.

Sie brauchen: nur den Browser und die Adresse der Installation. Es ist noch kein Konto nötig, und die Seite ist ohne Anmeldung erreichbar, solange noch kein Benutzer angelegt ist.

Achtung

Rufen Sie die Adresse gleich nach der Installation auf und schließen Sie die Einrichtung ab. Bis dahin kann jeder, der die Adresse erreicht, das erste Administratorkonto anlegen. Danach ist die Registrierung gesperrt, und die Seite leitet auf die Anmeldung um.

Sie haben zwei Wege:

Weg	Wann
„Neu einrichten“	Die Verwaltung beginnt mit heinzelhaus. Sie erfassen die Angaben zur Verwaltung und legen ein Administratorkonto an.
„Sicherung einspielen“	Der Server wurde neu aufgesetzt, und die Daten einer früheren heinzelhaus-Installation sollen zurückkehren. Konten, Einstellungen und Daten kommen aus der Sicherung.

Neu einrichten

Damit Ihre Verwaltung in heinzelhaus angelegt ist.

1. Klicken Sie auf „Neu einrichten“. Es erscheint ein Assistent mit drei Schritten: „Verwaltung“, „Adresse“ und „Administrator“. Er sagt: „Die Angaben zur Verwaltung lassen sich später in den Einstellungen ändern.“
2. Schritt 1, „Angaben zur Verwaltung“. Füllen Sie die Felder „Name der Verwaltung“, „Straße und Hausnummer“, „PLZ“, „Ort“, „Telefon“ und „E-Mail“ aus. Nur der „Name der Verwaltung“ ist Pflicht. Ohne ihn erscheint „Bitte den Namen der Verwaltung angeben.“ Unter dem Feld steht: „Erscheint auf Abrechnungen und im Briefkopf.“ Klicken Sie auf „Weiter“.
3. Schritt 2, „Adresse dieser Installation“. Das Feld „Domain (optional)“ lassen Sie im Zweifel leer, siehe unten. Klicken Sie auf „Weiter“.
4. Schritt 3, „Administratorkonto“. Tragen Sie „Ihr Name“, „E-Mail-Adresse“ und „Passwort“ ein und wiederholen Sie das Passwort unter „Passwort wiederholen“. Das Passwort braucht mindestens 12 Zeichen. Unter dem Feld zählt heinzelhaus mit.
5. Klicken Sie auf „Einrichtung abschließen“. Es erscheint „Einrichtung abgeschlossen.“ und heinzelhaus öffnet das Dashboard.

Unter den Feldern steht: „Dieses Konto erhält Administratorrechte. Danach ist die Registrierung gesperrt — weitere Benutzer legen Sie in den Einstellungen an.“ Der erste Benutzer wird also automatisch Administrator. Alle weiteren Konten legt ein Administrator an oder lädt sie per E-Mail ein, siehe Benutzer, Rollen und Rechte.

Die Adresse der Installation

heinzelhaus bildet manche Links selbst: den Link in der Einladungsmail, den Zugang zum Handwerkerportal und die Links in Benachrichtigungsmails. Die Adresse dafür kommt aus zwei Quellen:

1. aus dem Feld „Domain (optional)“ der Ersteinrichtung, falls Sie es ausgefüllt haben,
2. sonst aus dem Eintrag BETTER_AUTH_URL in der .env, den das Installationsskript gesetzt hat.

Im Feld „Domain (optional)“ tragen Sie nur die reine Domain ein, ohne https:// und ohne Pfad, zum Beispiel verwaltung.example.de. Schema, Port und Pfad entfernt heinzelhaus selbst. Eine IP-Adresse oder etwas, das keine Domain ist, übergeht es ohne Meldung. Der Assistent sagt dazu: „Im Zweifel leer lassen“. Das gilt bei einer Installation im lokalen Netz und wenn Sie die Domain schon bei der Installation angegeben haben.

Achtung

In den Einstellungen gibt es kein Feld, um die Domain später zu ändern. Das sagt Ihnen der Assistent im Schritt „Adresse“ unter „Später ändern“ auch. Eine hier eingetragene Domain geht für die Links vor und lässt sich danach nur noch direkt in der Datenbank ändern. Tragen Sie sie deshalb nur ein, wenn sie feststeht. Die Adresse der Installation selbst steht in der .env (BETTER_AUTH_URL, für Passkeys PASSKEY_RP_ID) und gilt nach einem Neustart der Container, siehe Installation.

Die Domain der Ersteinrichtung setzt nicht die Passkey-Domain. Passkeys richten sich allein nach PASSKEY_RP_ID in der .env.

Wenn das Speichern der Angaben scheitert

Das Administratorkonto wird zuerst angelegt, die Angaben zur Verwaltung danach. Scheitert nur das Speichern der Angaben, erscheint „Konto angelegt, Angaben nicht gespeichert“. Die Installation ist trotzdem benutzbar. Tragen Sie die Angaben nach unter Einstellungen → Reiter „Allgemein“ → Karte „Ihre Verwaltung“.

Sofort danach: starke Anmeldung einrichten

Das neue Administratorkonto arbeitet im Alltag sofort, mit Buchhaltung, Objekten und Kontakten. Einstellungen, Benutzerverwaltung, Sicherungen und Updates öffnen sich aber erst nach einer starken Anmeldung, also mit einem Passkey oder mit einer eingerichteten Authenticator-App. Klicken Sie auf das Zahnrad, führt heinzelhaus Sie deshalb zur Seite „Sicherheit“ mit dem Hinweis „Einstellungen und Updates: Bitte stark anmelden“.

Richten Sie gleich nach der Einrichtung eine der beiden Möglichkeiten ein. Wie das geht, steht unter Anmeldesicherheit und Zwei-Faktor-Pflicht.

Danach einstellen

Haben Sie sich stark angemeldet, richten Sie Ihre Installation Schritt für Schritt ein. Sie öffnen die Einstellungen über Seitenleiste → Verwaltung → „Einstellungen“ oder über das Zahnrad oben rechts.

Was	Wo	Mehr dazu
Angaben zur Verwaltung ändern oder ergänzen	Reiter „Allgemein“, Karte „Ihre Verwaltung“	auf dieser Seite
Impressum und Anbieterzeile	Reiter „Impressum“	Erscheinungsbild
Logo, Name und Farbe der Oberfläche	Reiter „Erscheinungsbild“	Erscheinungsbild
E-Mail-Versand	Reiter „E-Mail“	Mailversand
Briefkopf für Schreiben und PDF	Reiter „Briefkopf“	Briefkopf
Team einladen, Rollen und Rechte	Reiter „Benutzer“	Benutzer, Rollen und Rechte
Datensicherung und Zeitplan	Reiter „Backup“	Datensicherung und Wiederherstellung
Bisherige Software übernehmen	Seitenleiste → Verwaltung → „Datenübernahme“	Überblick und Ablauf

Für die Angaben unter „Allgemein“ gibt es keine Pflichtfelder. Dieselben Angaben fragt die Ersteinrichtung ab. Sie erscheinen auf Briefen und Abrechnungen. Das Impressum greift auf sie zurück, solange es nicht gepflegt ist.

Sicherung einspielen

Damit ein neu aufgesetzter Server mit dem alten Datenbestand weiterarbeitet, einschließlich der Konten, Rechte und Einstellungen.

Sie brauchen: eine vollständige Sicherung aus heinzelhaus oder aus CasaTastic, dem Namen der Software bis Version 0.6 (siehe Datensicherung und Wiederherstellung), und bei einer verschlüsselten Sicherung das Passwort.

Das Einspielen ersetzt den gesamten Datenbestand. Es geht nur hier und nur, solange noch kein Benutzer angelegt ist. Auf einer benutzten Installation lehnt heinzelhaus es ab: „Diese Installation wird bereits benutzt. Eine Wiederherstellung ist hier nicht möglich.“

1. Installieren Sie heinzelhaus neu, wie unter Installation beschrieben, und öffnen Sie die Adresse im Browser.

2. Packen Sie die Dateien einer Sicherung zu einer einzigen Datei mit der Endung .tar.gz zusammen. Sie brauchen den Datenbank-Dump (datenbank.dump, bei verschlüsselten Sicherungen datenbank.dump.enc) und das Dateien-Archiv (dateien.tar.gz oder dateien.tar.gz.enc). Die beim Herunterladen vergebenen Namen werden erkannt, auch die aus der Zeit vor 1.0 (casatastic-…). Legen Sie nicht die Dateien mehrerer Sicherungen in dasselbe Archiv. Auf dem Server oder auf einem Linux- oder macOS-Rechner packen Sie sie in einem Ordner zusammen, der nur die Dateien dieser einen Sicherung enthält:

   tar czf ../sicherung.tar.gz *

3. Ist die Sicherung verschlüsselt, setzen Sie zuerst das Häkchen bei „Die Sicherung ist mit einem Passwort verschlüsselt“ und tragen das „Passwort der Sicherung“ ein. Das Feld bittet darum, es vor der Auswahl der Datei auszufüllen.

4. Klicken Sie auf „Sicherung einspielen“ und wählen Sie die Datei .tar.gz aus.

5. Es erscheint „Sicherung wird eingespielt …“. Bei großen Datenbeständen kann das dauern. Schließen Sie die Seite nicht.

6. Am Ende steht „Sicherung eingespielt. Bitte melden Sie sich an.“ Melden Sie sich mit einem Konto aus der Sicherung an.

Achtung

Die .env des alten Servers gehört nicht zur Sicherung. Der Schlüssel BETTER_AUTH_SECRET darin schützt die gespeicherten Zugangsdaten der Authenticator-Apps. Hat die neue Installation einen anderen Schlüssel, funktionieren eingerichtete Authenticator-Apps nach dem Einspielen nicht mehr. Ein Passkey bleibt gültig, wenn die Domain dieselbe ist (PASSKEY_RP_ID). Wer sich nicht mehr anmelden kann, bittet seine IT, den zweiten Faktor mit dem Skript scripts/2fa-zuruecksetzen.sh zurückzusetzen, siehe Anmeldesicherheit und Zwei-Faktor-Pflicht. Besser ist es, den Schlüssel aus der alten .env in die neue zu übernehmen, bevor Sie die Sicherung einspielen.

Gut zu wissen

• heinzelhaus prüft das Passwort, bevor es etwas ersetzt. Ein falsches Passwort lässt Ihre frische Installation unberührt.
• Erst werden die Dateien eingespielt, dann die Datenbank. Bricht das Entpacken ab, bleibt die Datenbank unberührt, und die Installation lässt sich weiter einrichten.
• Der Datenbank-Dump ist in jeder Sicherung vollständig. Das Dateien-Archiv einer inkrementellen Sicherung enthält aber nur die seit dem vollständigen Backup geänderten Dateien. Über die Ersteinrichtung lässt sich nur ein Dateien-Archiv einspielen. Nehmen Sie deshalb ein vollständiges Backup, oder legen Sie die Dateien inkrementeller Sicherungen von Hand nach.

Häufige Fehler

Meldung	Ursache	Lösung
„Bitte den Namen der Verwaltung angeben.“	Das Feld „Name der Verwaltung“ ist leer.	Tragen Sie den Namen ein.
„Die Passwörter stimmen nicht überein.“	„Passwort“ und „Passwort wiederholen“ unterscheiden sich.	Geben Sie beide Felder neu ein.
„Einrichtung fehlgeschlagen“	Das Konto konnte nicht angelegt werden, zum Beispiel wegen eines zu kurzen Passworts.	Prüfen Sie die Angaben. Das Passwort braucht mindestens 12 Zeichen.
„Konto angelegt, Angaben nicht gespeichert“	Das Konto gibt es, die Angaben zur Verwaltung nicht.	Tragen Sie sie unter Einstellungen → „Allgemein“ nach.
„Diese Installation wird bereits benutzt. Eine Wiederherstellung ist hier nicht möglich.“	Es gibt schon einen Benutzer.	Das Einspielen geht nur auf einer frischen Installation. Installieren Sie neu oder fragen Sie Ihre IT, siehe Datensicherung und Wiederherstellung.
„Diese Sicherung ist verschlüsselt. Bitte geben Sie das Passwort an …“	Das Passwort fehlt.	Setzen Sie das Häkchen für die Verschlüsselung, tragen Sie das Passwort ein und wählen Sie die Datei erneut.
„Das Passwort ist falsch …“	Das Passwort stimmt nicht.	Prüfen Sie es. Ohne das richtige Passwort lässt sich die Sicherung nicht öffnen.
„Die Sicherung ist beschädigt oder wurde nachträglich verändert. Bitte spielen Sie eine andere Kopie ein.“	Die Datei ist unvollständig übertragen oder verändert worden.	Laden Sie die Sicherung erneut herunter und packen Sie sie neu zusammen.
„In der Sicherung fehlt datenbank.dump — sie ist unvollständig oder gehört nicht zu heinzelhaus.“	Der Datenbank-Dump fehlt im Archiv, oder mehrere Sicherungen liegen darin.	Packen Sie die Dateien einer einzigen Sicherung zusammen.

Noch nicht möglich

• Die Domain der Installation lässt sich in den Einstellungen nicht nachtragen oder ändern. Die Adresse der Installation ändert Ihre IT in der .env.
• Eine Sicherung im laufenden Betrieb über die Oberfläche einzuspielen, geht noch nicht. Die Ersteinrichtung ist der einzige Weg in der Oberfläche. Im laufenden Betrieb stellt Ihre IT die Daten nach der Anleitung LIESMICH.txt wieder her, siehe Datensicherung und Wiederherstellung.
• Eine Sicherung aus einer anderen Software als heinzelhaus oder CasaTastic lässt sich hier nicht einspielen. Für Karthago und PowerHaus gibt es die Datenübernahme.

Weiter geht es hier

• Anmeldesicherheit und Zwei-Faktor-Pflicht: Passkey oder Authenticator-App einrichten.
• Benutzer, Rollen und Rechte: Ihr Team einladen.
• Anmelden: So melden sich Ihre Mitarbeitenden an.