assetsTracker/LOCAL_SETUP.md

DefektTrack / AssetsTracker – lokal starten (Schritt für Schritt)

Voraussetzungen

• Node.js (z. B. v18 oder v20) – nodejs.org
• Appwrite – entweder:
  • Appwrite Cloud: cloud.appwrite.io (kostenloser Account), oder
  • Appwrite lokal mit Docker (siehe unten)

---

Schritt 1: Abhängigkeiten installieren

Im Projektordner im Terminal ausführen:

npm install

---

Schritt 2: Umgebungsvariablen einrichten

1. Datei .env anlegen (im Projektroot, neben package.json):

   copy .env.example .env
   

   (Unter Linux/macOS: cp .env.example .env)

2. .env bearbeiten und die Platzhalter ersetzen:

   • VITE_APPWRITE_ENDPOINT
     • Appwrite Cloud: https://cloud.appwrite.io/v1
     • Lokal mit Docker: http://localhost/v1 (oder deine Appwrite-URL)
   • VITE_APPWRITE_PROJECT_ID
     Projekt-ID aus der Appwrite Console (Projekt → Settings).
   • VITE_APPWRITE_DATABASE_ID
     Optional; Standard: defekttrack_db.
   • APPWRITE_ENDPOINT
     Gleich wie VITE_APPWRITE_ENDPOINT (wird nur für npm run setup genutzt).
   • APPWRITE_API_KEY
     API-Key aus Appwrite: Projekt → Settings → API Keys → „Create API Key“ (mit Scopes z. B. für Databases, Users, Teams).
     Wichtig: Den Key nur für Setup verwenden und nicht im Frontend oder in Git committen.
   • ADMIN_SECRET / VITE_ADMIN_SECRET (gleicher Wert)
     Nur nötig, wenn du im Admin-Panel Benutzer hinzufügen nutzen willst. Beliebiges geheimes Token; das Backend prüft es beim Aufruf von POST /api/admin/create-user.

---

Schritt 3: Appwrite-Projekt und Datenbank einrichten (einmalig)

Damit die App funktioniert, müssen Datenbank, Collections und ein Admin-User angelegt werden:

npm run setup

Das Skript legt u. a. an:

• Datenbank und Collections (locations, users_meta, lagerstandorte, assets, audit_logs)
• Teams (admin, firmenleiter, filialleiter, service, lager)
• Standard-Filiale „Hauptfiliale“
• Admin-User: admin@defekttrack.local / Admin1234!

Nach dem Setup den API-Key aus der .env entfernen oder durch einen eingeschränkten Key ersetzen, wenn du ihn nicht mehr brauchst.

---

Schritt 4: Entwicklungsserver starten

npm run dev

Die App läuft dann z. B. unter http://localhost:5173 (oder der in der Konsole angezeigten URL).

Benutzer aus dem Admin-Panel anlegen: Dafür muss zusätzlich der API-Server laufen (in einem zweiten Terminal):

npm run dev:api

Vite leitet Anfragen an /api an diesen Server weiter. In der .env müssen ADMIN_SECRET und VITE_ADMIN_SECRET (gleicher Wert) gesetzt sein.

---

Kurzüberblick

Befehl	Beschreibung
npm install	Abhängigkeiten installieren
npm run setup	Appwrite-Datenbank & Admin einrichten (einmalig)
npm run dev	App lokal starten (Vite Dev-Server)
npm run dev:api	API-Server für „Benutzer hinzufügen“ (zweites Terminal)
npm run build	Produktions-Build erstellen
npm run preview	Build lokal ansehen

---

Optional: Appwrite komplett lokal mit Docker

Wenn du keinen Appwrite-Cloud-Account nutzen willst:

1. Docker installieren.

2. Appwrite starten (offizielle Anleitung: appwrite.io/docs/installation).

   Beispiel mit Docker Compose im Projektordner:

   curl -o docker-compose.yml https://appwrite.io/docker-compose.yml
   docker compose up -d
   

3. Im Browser http://localhost (oder die angegebene URL) öffnen und ein neues Projekt anlegen.

4. In der .env eintragen:

   • VITE_APPWRITE_ENDPOINT = http://localhost/v1 (oder deine Appwrite-URL)
   • APPWRITE_ENDPOINT = gleicher Wert
   • VITE_APPWRITE_PROJECT_ID = ID des neu angelegten Projekts
   • APPWRITE_API_KEY = API-Key aus dem Projekt (Settings → API Keys)

Dann wie oben Schritt 3 (npm run setup) und Schritt 4 (npm run dev) ausführen.

---

Häufige Probleme

• „Bitte APPWRITE_ENDPOINT, VITE_APPWRITE_PROJECT_ID und APPWRITE_API_KEY in .env setzen“
  → .env anlegen (aus .env.example) und alle drei Werte eintragen.

• CORS / Verbindungsfehler
  → Endpoint-URL in .env prüfen (z. B. https://cloud.appwrite.io/v1 ohne abschließenden Schrägstrich außer /v1). Bei lokalem Appwrite: korrekte Docker-URL und ggf. Host in Appwrite konfigurieren.

• Login funktioniert nicht
  → Nach npm run setup mit admin@defekttrack.local / Admin1234! einloggen. Bei Cloud: ggf. E-Mail-Verifizierung in den Appwrite-Projekteinstellungen anpassen.