# Installation Diese Anleitung beschreibt die Installation einer lokalen Company-Tool-Instanz mit PostgreSQL und Backend. Sie ist so aufgebaut, dass sie später als Grundlage für Installationen bei Organisationen verwendet werden kann. ## Voraussetzungen Für eine lokale Installation werden benötigt: - PostgreSQL 16 oder neuer - Rust/Cargo - Node.js 24 oder neuer, für Webfrontend und Kommunikationstests Optional: - Docker oder Podman, wenn PostgreSQL als Container laufen soll ## PostgreSQL per Docker Compose Im Projekt liegt eine vorbereitete PostgreSQL-Konfiguration. ```bash docker compose up -d postgres ``` Die Standardwerte sind: - Host: `localhost` - Port: `5432` - Datenbank: `companytool` - Benutzer: `companytool` - Passwort: `companytool` Danach `.env` anlegen: ```bash cp .env.example .env ``` Verbindung prüfen: ```bash psql "postgres://companytool:companytool@localhost:5432/companytool" -c "select 1;" ``` ## PostgreSQL manuell anlegen Falls PostgreSQL bereits auf einem Server installiert ist, kann die Datenbank manuell angelegt werden. Als PostgreSQL-Admin ausführen: ```sql create user companytool with password 'companytool'; create database companytool owner companytool; ``` Empfohlene produktive Anpassungen: - eigenes starkes Passwort verwenden - Datenbank nur aus dem internen Netz erreichbar machen - PostgreSQL-Backups einrichten - Zugriff über Firewall einschränken Beispiel mit sicherem Passwort: ```sql create user companytool with password ''; create database companytool owner companytool; ``` Dann `.env` anpassen: ```env DATABASE_URL=postgres://companytool:@localhost:5432/companytool BACKEND_BIND=127.0.0.1:8080 VITE_WS_URL=ws://localhost:8080/ws ``` ## Backend starten ```bash cargo run -p companytool-backend ``` Beim Start führt das Backend aktuell die Basistabelle für den Testdatensatz automatisch aus und legt bei Bedarf einen ersten Datensatz an. Die SQLx- Migrationen unter `backend/migrations/` werden beim Backend-Start automatisch ausgeführt. Health-Check: ```bash curl http://127.0.0.1:8080/health ``` Erwartete Antwort: ```json {"status":"ok"} ``` ## Verschlüsselte Kommunikation testen Backend in einem Terminal starten: ```bash cargo run -p companytool-backend ``` In einem zweiten Terminal: ```bash node scripts/communication-test.mjs ``` Der Test prüft: - zwei echte WebSocket-Clients - `hello`/`hello_ack`-Handshake - eigener AES-256-GCM-Session-Key pro Client - verschlüsselter Snapshot vom Backend - verschlüsselte `subscribe`- und `ping`-Nachrichten - verschlüsseltes `pong`-Event an beide Clients - keine fachlichen Klartextmarker in den Rohframes Erwartetes Ergebnis: ```text client-a handshake, encrypted snapshot and subscribe ok client-b handshake, encrypted snapshot and subscribe ok encrypted multi-client communication test ok ``` ## Onboarding-API testen Mit laufendem Backend: ```bash node scripts/api-onboarding-test.mjs http://127.0.0.1:8080 ``` Der Test legt eine Organization-Registrierung an, lädt Liste und Detail, schaltet die Organization frei, testet den Login mit Initialpasswort, speichert Firmendaten, prüft Rechte-Negativfälle, lädt einen weiteren User ein und prüft die Rechteänderung. ## Schema-Migration testen Mit laufendem Backend und PostgreSQL: ```bash node scripts/schema-migration-test.mjs http://127.0.0.1:8080 ``` Der Test legt eine Firma an, führt die Mandantenschema-Provisionierung erneut aus und prüft, dass Nummernkreise, Rollen und spätere Tabellen wie Kommunikation weiterhin funktionieren. Dadurch werden idempotente Mandantenmigrationen früh erkannt. ## Live-Events testen Mit laufendem Backend und PostgreSQL kann der Kommunikationstest zusätzlich eine fachliche Änderung über die REST-API auslösen: ```bash node scripts/communication-test.mjs ws://127.0.0.1:8080/ws http://127.0.0.1:8080 ``` Der Test prüft dann neben Handshake, Verschlüsselung und Ping/Pong auch, dass eine neu angelegte Aktivität als verschlüsseltes `record_changed`-Event bei zwei verbundenen Clients ankommt. ## Standardcheck Der Standardcheck bündelt die schnellen Prüfungen ohne laufendes Backend: ```bash bash scripts/standard-check.sh ``` Enthalten sind: - Rust-Formatprüfung - `cargo check --workspace` - Headless-Unit-Tests des Desktopclients - Syntaxprüfung der Node-Testskripte - Webfrontend-Build inklusive Vue/TypeScript-Prüfung ## Lokale Testdaten anlegen Mit laufendem Backend kann ein reproduzierbarer Entwicklungsdatensatz erzeugt werden: ```bash node scripts/dev-seed.mjs http://127.0.0.1:8080 ``` Das Skript nutzt den Dev-Bootstrap, legt eine Firma, einen Admin-Zugang, Skonto, Kunde, Lieferant, Artikel und Aktivität an und gibt die Zugangsdaten als JSON aus. Der Endpunkt ist nur im Entwicklungsbetrieb vorgesehen. ## Kommunikation ohne PostgreSQL testen Falls PostgreSQL noch nicht eingerichtet ist, kann nur die Kommunikationsschicht getestet werden. Terminal 1: ```bash COMMUNICATION_TEST_MODE=1 cargo run -p companytool-backend ``` Terminal 2: ```bash node scripts/communication-test.mjs ``` Dieser Modus ist nur für Entwicklung und Tests gedacht. ## Webfrontend starten ```bash cd web-frontend npm install npm run dev ``` Standard-URL: ```text http://localhost:5175/ ``` Im Entwicklungsbetrieb leitet Vite `/api` und `/ws` standardmäßig an `http://127.0.0.1:8080` weiter. Wenn das Backend auf einem anderen Port läuft, wird die Zieladresse so gesetzt: ```bash VITE_BACKEND_ORIGIN=http://127.0.0.1:18084 npm run dev ``` ### Lokalen Testzugang ohne E-Mail anlegen Im Entwicklungsbuild ist auf der Login-Seite ein Dev-Bootstrap verfügbar. Damit wird eine lokale Testfirma mit erstem User angelegt. Das Initialpasswort wird direkt in der Oberfläche angezeigt, weil auf Entwicklungsrechnern kein E-Mail-Versand vorausgesetzt wird. Alternativ per API: ```bash curl -s -X POST http://127.0.0.1:8080/api/v1/dev/bootstrap-local \ -H 'Content-Type: application/json' \ -d '{"organization_name":"Lokale Testfirma","email":"admin@example.test"}' ``` Produktiv ist dieser Endpunkt nicht vorgesehen. Er ist nur im Debug-Build oder mit `COMPANYTOOL_DEV_MODE=1` aktiv. ## Desktopclient starten Der native Client liest seine Server-Konfiguration aus: ```text desktop-client/companytool-client.toml ``` Minimaler Inhalt: ```toml [server] api_base_url = "http://localhost:8080" ws_url = "ws://localhost:8080/ws" ``` API- und WebSocket-URL können überschrieben werden: ```bash cargo run -p companytool-desktop-client -- --api-url http://127.0.0.1:8080 --ws-url ws://127.0.0.1:8080/ws ``` Oder mit expliziter Config-Datei: ```bash cargo run -p companytool-desktop-client -- --config /pfad/companytool-client.toml ``` Alternativ per Umgebungsvariablen: ```bash COMPANYTOOL_CLIENT_CONFIG=/pfad/companytool-client.toml cargo run -p companytool-desktop-client COMPANYTOOL_API_BASE_URL=http://127.0.0.1:8080 cargo run -p companytool-desktop-client COMPANYTOOL_WS_URL=ws://127.0.0.1:8080/ws cargo run -p companytool-desktop-client ``` Start mit Standardkonfiguration: ```bash cargo run -p companytool-desktop-client ``` ## Nativen Client testen Der native Client hat Headless-Tests. Dabei wird kein Fenster geöffnet. ### Kommunikation Backend starten: ```bash COMMUNICATION_TEST_MODE=1 cargo run -p companytool-backend ``` Test ausführen: ```bash cargo run -p companytool-desktop-client -- --communication-test ``` Optional gegen eine andere WebSocket-URL oder Config-Datei: ```bash cargo run -p companytool-desktop-client -- --communication-test --ws-url ws://127.0.0.1:18081/ws cargo run -p companytool-desktop-client -- --communication-test --config /pfad/companytool-client.toml ``` Erwartetes Ergebnis: ```text native client communication test ok ``` ### Registrierung Für den Registrierungstest muss das Backend mit PostgreSQL laufen: ```bash cargo run -p companytool-backend ``` Test ausführen: ```bash cargo run -p companytool-desktop-client -- --registration-test --api-url http://127.0.0.1:8080 ``` Optional können Firmenname und E-Mail gesetzt werden: ```bash cargo run -p companytool-desktop-client -- --registration-test --api-url http://127.0.0.1:8080 --organization-name "Beispiel GmbH" --email admin@example.org ``` Erwartetes Ergebnis: ```text native client registration test ok ``` ## Hinweise für Organisations-Installationen Für Installationen bei Organisationen gelten zusätzlich: - produktiv nur HTTPS/WSS verwenden - PostgreSQL-Passwort individuell vergeben - `.env` nicht an Dritte weitergeben - regelmäßige Datenbank-Backups einrichten - Zugriff auf PostgreSQL nicht öffentlich freigeben - Backend hinter Reverse Proxy betreiben - Zertifikate für lokale oder öffentliche Nutzung sauber einrichten - spätere Versionen werden genau eine Organisation pro lokaler Installation unterstützen ## Fehlerbehebung PostgreSQL nicht erreichbar: ```bash pg_isready -h localhost -p 5432 ``` Backend kann Datenbank nicht öffnen: - `DATABASE_URL` in `.env` prüfen - PostgreSQL-Dienst prüfen - Benutzer, Passwort und Datenbanknamen prüfen Port bereits belegt: ```bash BACKEND_BIND=127.0.0.1:18080 cargo run -p companytool-backend node scripts/communication-test.mjs ws://127.0.0.1:18080/ws ```