135 lines
4.8 KiB
Markdown
135 lines
4.8 KiB
Markdown
# DefektTrack / AssetsTracker – lokal starten (Schritt für Schritt)
|
||
|
||
## Voraussetzungen
|
||
|
||
- **Node.js** (z. B. v18 oder v20) – [nodejs.org](https://nodejs.org)
|
||
- **Appwrite** – entweder:
|
||
- **Appwrite Cloud**: [cloud.appwrite.io](https://cloud.appwrite.io) (kostenloser Account), oder
|
||
- **Appwrite lokal** mit Docker (siehe unten)
|
||
|
||
---
|
||
|
||
## Schritt 1: Abhängigkeiten installieren
|
||
|
||
Im Projektordner im Terminal ausführen:
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
---
|
||
|
||
## Schritt 2: Umgebungsvariablen einrichten
|
||
|
||
1. **Datei `.env` anlegen** (im Projektroot, neben `package.json`):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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](https://www.docker.com/products/docker-desktop/) installieren.
|
||
2. Appwrite starten (offizielle Anleitung: [appwrite.io/docs/installation](https://appwrite.io/docs/installation)).
|
||
|
||
Beispiel mit Docker Compose im Projektordner:
|
||
|
||
```bash
|
||
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.
|