company-tool/INSTALL.md

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.

docker compose up -d postgres

Die Standardwerte sind:

• Host: localhost
• Port: 5432
• Datenbank: companytool
• Benutzer: companytool
• Passwort: companytool

Danach .env anlegen:

cp .env.example .env

Verbindung prüfen:

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:

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:

create user companytool with password '<sicheres-passwort>';
create database companytool owner companytool;

Dann .env anpassen:

DATABASE_URL=postgres://companytool:<sicheres-passwort>@localhost:5432/companytool
BACKEND_BIND=127.0.0.1:8080
VITE_WS_URL=ws://localhost:8080/ws

Backend starten

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:

curl http://127.0.0.1:8080/health

Erwartete Antwort:

{"status":"ok"}

Verschlüsselte Kommunikation testen

Backend in einem Terminal starten:

cargo run -p companytool-backend

In einem zweiten Terminal:

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:

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:

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:

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:

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 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:

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:

COMMUNICATION_TEST_MODE=1 cargo run -p companytool-backend

Terminal 2:

node scripts/communication-test.mjs

Dieser Modus ist nur für Entwicklung und Tests gedacht.

Webfrontend starten

cd web-frontend
npm install
npm run dev

Standard-URL:

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:

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:

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:

desktop-client/companytool-client.toml

Minimaler Inhalt:

[server]
api_base_url = "http://localhost:8080"
ws_url = "ws://localhost:8080/ws"

API- und WebSocket-URL können überschrieben werden:

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:

cargo run -p companytool-desktop-client -- --config /pfad/companytool-client.toml

Alternativ per Umgebungsvariablen:

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:

cargo run -p companytool-desktop-client

Nativen Client testen

Der native Client hat Headless-Tests. Dabei wird kein Fenster geöffnet.

Kommunikation

Backend starten:

COMMUNICATION_TEST_MODE=1 cargo run -p companytool-backend

Test ausführen:

cargo run -p companytool-desktop-client -- --communication-test

Optional gegen eine andere WebSocket-URL oder Config-Datei:

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:

native client communication test ok

Registrierung

Für den Registrierungstest muss das Backend mit PostgreSQL laufen:

cargo run -p companytool-backend

Test ausführen:

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:

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:

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:

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:

BACKEND_BIND=127.0.0.1:18080 cargo run -p companytool-backend
node scripts/communication-test.mjs ws://127.0.0.1:18080/ws