Anleitung · Windows

PraxisZeit unter Windows einrichten

Quick-Start für Windows 10 22H2, Windows 11 und Windows Server 2019+. In fünf Schritten vom Download zum laufenden Praxis-Server.

Voraussetzungen

Vor dem Start prüfen
  • Windows 10 22H2, Windows 11 oder Windows Server 2019/2022
  • Administrator-Rechte auf dem Praxis-Rechner
  • Mindestens 5 GB freier Festplattenspeicher
  • Port 443 frei (HTTPS) — wird vom Installer in der Firewall freigegeben (anderer Port möglich, siehe „Netzwerk und Port")
  • Kein Internetzugang nötig — PostgreSQL liegt dem Paket bei

Download

Laden Sie die aktuelle Version aus dem Shop herunter: /download. Wählen Sie die Datei mit dem Suffix windows.zip.

Prüfen Sie anschließend die SHA-256-Prüfsumme — der erwartete Wert steht direkt unter der Download-Schaltfläche:

certutil -hashfile praxiszeit-<version>-windows.zip SHA256

Entpacken und SmartScreen entsperren

Windows blockiert heruntergeladene ZIP-Dateien aus dem Internet standardmäßig. Das ist der häufigste Stolperstein.

  1. Rechtsklick auf die ZIP-Datei → Eigenschaften
  2. Unten im Tab Allgemein bei Sicherheit die Checkbox „Zulassen" aktivieren
  3. Übernehmen klicken — vor dem Entpacken
  4. Erst dann die ZIP entpacken (Rechtsklick → „Alle extrahieren")

Ziel muss ein neuer oder leerer Ordner sein (z. B. C:\PraxisZeit). Seit 1.23.0 ist eine Neuinstallation in einen Ordner mit fremden Inhalten gesperrt („Setup gesperrt – im Installationsordner liegen Dateien, die nicht zu PraxisZeit gehören"): die aufgelisteten Einträge entfernen und erneut ausführen oder in einen neuen, leeren Ordner entpacken.

Wenn Sie diesen Schritt vergessen, blockiert Windows später jede.exe und .bat im entpackten Verzeichnis.

Installation — zwei Wege

Im entpackten Verzeichnis liegen zwei Installationsvarianten. Wählen Sie eine — beide führen zum selben Ergebnis.

Empfohlen: GUI-Installer

ab v1.4.0

Doppelklick auf PraxisZeit.Setup.exe im Verzeichnis installer/setup/. Der Wizard erkennt PostgreSQL, legt das Konfigurationsverzeichnis an und installiert den Windows-Dienst. Keine Konsole, keine Skripte.

Klassisch: setup.bat

Rechtsklick auf installer/windows/setup.bat → „Als Administrator ausführen". Das Skript installiert das mitgelieferte PostgreSQL und prüft die mitgelieferten Python-Abhängigkeiten – seit 1.23.0 lädt es nichts mehr aus dem Internet.

# In einer Administrator-PowerShell:
cd C:\Pfad\zu\praxiszeit\installer\windows
.\setup.bat

Achtung: Bearbeiten Sie praxiszeit.conf niemals mit Notepad — Notepad schreibt eine UTF-8-BOM, die den Dienst beim Start crashen lässt. Verwenden Sie VS Code oder Notepad++ und speichern Sie als UTF-8 ohne BOM.

Windows-Dienst installieren

Damit PraxisZeit beim Hochfahren des Rechners automatisch startet, registrieren Sie den Dienst. Bei der GUI-Variante ist dies bereits erledigt — bei setup.bat rufen Sie zusätzlich auf:

# Rechtsklick → "Als Administrator ausführen"
installer\windows\install-service.bat

Das Skript registriert den Dienst PraxisZeit, setzt den Starttyp auf Automatisch und öffnet die Firewall-Regel für Port 443.

Im Browser öffnen

Öffnen Sie einen Browser auf demselben Rechner:

https://localhost

Aus dem Praxisnetz erreichen Sie den Server unter dem Computernamen, z.B. https://praxis-pc oder über die lokale IP-Adresse. Beim ersten Aufruf akzeptieren Sie das selbstsignierte Zertifikat (für die Produktivnutzung empfehlen wir ein Zertifikat aus Ihrer internen PKI).

Anschließend melden Sie sich mit dem Admin-Konto an, das Sie bei der Installation festgelegt haben, und können Mitarbeiter und Arbeitszeiten erfassen.

Netzwerk und Port

Warum „localhost" und die IP-Adresse funktionieren

PraxisZeit läuft auf dem Praxis-Rechner als eigener kleiner Webserver. Standardmäßig nutzt er Port 443, den üblichen Port für verschlüsselte Webseiten (HTTPS). Diesen Port ergänzt der Browser bei https:// selbst, deshalb steht er nicht in der Adresse. Der Server antwortet auf allen Netzwerkverbindungen des Rechners:

  • https://localhost ist der Rechner selbst und funktioniert nur direkt an diesem PC.
  • Über den Computernamen oder die IP-Adresse (z.B. https://192.168.1.20) erreichen die anderen Praxis-PCs PraxisZeit. Der Installer gibt den Port dafür in der Windows-Firewall frei.

Andere Programme auf demselben Rechner

Jeder Port kann immer nur von einem Programm gleichzeitig belegt werden. Programme mit eigener Browser-Oberfläche auf anderen Ports stören sich nicht und laufen problemlos nebeneinander. Belegt bereits ein anderes Programm Port 443, warnt der GUI-Installer auf der Seite „Ports". Ohne Änderung startet PraxisZeit dann nicht. Wählen Sie in diesem Fall einen anderen Port, z.B. 8443. Die Adresse lautet dann https://praxis-pc:8443.

Ob ein Port belegt ist, zeigt eine Eingabeaufforderung. Die letzte Spalte ist die Prozess-ID; im Task-Manager (Reiter Details, Spalte PID) sehen Sie, welches Programm dazu gehört:

netstat -ano | findstr :443

Anderer PostgreSQL auf dem Rechner

Läuft auf dem Rechner bereits ein anderer PostgreSQL-Server auf Port 5432 (zum Beispiel von einer anderen Praxissoftware), bekommt PraxisZeit für seine Datenbank einen eigenen Port. Im GUI-Installer tragen Sie ihn auf der Seite „Ports" im Feld „Datenbank-Port (nur Windows)" ein, z.B. 5433. Nachträglich ergänzen Sie in der Konfigurationsdatei einen Abschnitt [database] und starten den Dienst neu (erlaubt sind Ports von 1024 bis 65535, ohne Eintrag gilt 5432):

[database]
port = 5433

Belegt ein fremder Server den Port, erkennt PraxisZeit das: Der Dienst bleibt gestoppt und meldet in logs\service-stderr.log, dass der Port von einem anderen PostgreSQL belegt ist. Es wird nichts angelegt oder verändert, Ihr fremder Server bleibt unberührt. Tragen Sie dann einen freien Port ein und starten Sie den Dienst neu. Wenn Sie PraxisZeit später über den GUI-Installer reparieren, tragen Sie den Datenbank-Port dort erneut ein.

Port nachträglich ändern

Tragen Sie den neuen Port in config\praxiszeit.conf im Installationsverzeichnis ein (speichern als UTF-8 ohne BOM, nicht mit Notepad):

[server]
port = 8443

Geben Sie dann in einer Administrator-Eingabeaufforderung den neuen Port in der Firewall frei und starten Sie den Dienst neu:

netsh advfirewall firewall add rule name="PraxisZeit 8443" dir=in action=allow protocol=TCP localport=8443
net stop PraxisZeit
net start PraxisZeit

Troubleshooting

Die drei häufigsten Probleme — und wie Sie sie in unter einer Minute lösen.

Windows SmartScreen blockt setup.exe

Klicken Sie im SmartScreen-Dialog auf „Weitere Informationen" → „Trotzdem ausführen". Alternativ entsperren Sie die ZIP vor dem Entpacken (siehe Schritt 2). Die Installer sind nicht signiert, weil wir kein EV-Zertifikat einsetzen — dieselbe Praxis wie bei vielen Open-Source-Tools.

Dienst crashed direkt nach dem Start

Fast immer Ursache: praxiszeit.conf wurde mit Notepad gespeichert und enthält eine UTF-8-BOM. Öffnen Sie die Datei in VS Code, prüfen Sie unten rechts die Codierung („UTF-8" — nicht „UTF-8 with BOM") und speichern Sie neu. Im Ereignisprotokoll erscheint dabei ein Fehler YAML parse error at line 1.

Nach Update: alte Oberfläche oder Login-Schleife

Browser-Cache leeren — Strg + F5 oder Strg + Shift + R. Alternativ einmal im Inkognito-Modus öffnen, um den Cache zu umgehen.

Weitere Stolperfallen sind im Detail dokumentiert: NATIVE-WINDOWS-PITFALLS.md

Vollständige Windows-Anleitung mit allen Stolperfallen

Die ausführliche Dokumentation auf GitHub deckt Server-Setups, Reverse-Proxy mit eigenem Zertifikat, automatische Backups und alle bekannten Windows-spezifischen Eigenheiten ab — gepflegt vom PraxisZeit-Team und der Community.