chore: Docs umstrukturiert, Client-Updates, Scripts nach scripts/
This commit is contained in:
373
docs/setup/SETUP_GUIDE.md
Normal file
373
docs/setup/SETUP_GUIDE.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# EmailSorter - Einrichtungsanleitung
|
||||
|
||||
Diese Anleitung führt dich durch die komplette Einrichtung von EmailSorter.
|
||||
|
||||
---
|
||||
|
||||
## Inhaltsverzeichnis
|
||||
|
||||
1. [Voraussetzungen](#voraussetzungen)
|
||||
2. [Appwrite einrichten](#1-appwrite-einrichten)
|
||||
3. [Stripe einrichten](#2-stripe-einrichten)
|
||||
4. [Google OAuth einrichten](#3-google-oauth-einrichten-gmail)
|
||||
5. [Microsoft OAuth einrichten](#4-microsoft-oauth-einrichten-outlook)
|
||||
6. [Mistral AI einrichten](#5-mistral-ai-einrichten)
|
||||
7. [Projekt starten](#6-projekt-starten)
|
||||
8. [Fehlerbehebung](#fehlerbehebung)
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- Node.js 18+ installiert
|
||||
- npm oder yarn
|
||||
- Git
|
||||
|
||||
---
|
||||
|
||||
## 1. Appwrite einrichten
|
||||
|
||||
### 1.1 Account erstellen
|
||||
|
||||
1. Gehe zu [cloud.appwrite.io](https://cloud.appwrite.io)
|
||||
2. Erstelle einen kostenlosen Account
|
||||
3. Erstelle ein neues Projekt (z.B. "EmailSorter")
|
||||
|
||||
### 1.2 API Key erstellen
|
||||
|
||||
1. Gehe zu **Settings** → **API Credentials**
|
||||
2. Klicke auf **Create API Key**
|
||||
3. Name: `EmailSorter Backend`
|
||||
4. Wähle **alle Berechtigungen** aus (Full Access)
|
||||
5. Kopiere den API Key
|
||||
|
||||
### 1.3 Datenbank erstellen
|
||||
|
||||
1. Gehe zu **Databases**
|
||||
2. Klicke auf **Create Database**
|
||||
3. Name: `email_sorter_db`
|
||||
4. Kopiere die **Database ID**
|
||||
|
||||
### 1.4 Bootstrap ausführen
|
||||
|
||||
```bash
|
||||
cd server
|
||||
npm run bootstrap:v2
|
||||
```
|
||||
|
||||
Dies erstellt automatisch alle benötigten Collections:
|
||||
- `products`
|
||||
- `questions`
|
||||
- `submissions`
|
||||
- `answers`
|
||||
- `orders`
|
||||
- `email_accounts`
|
||||
- `email_stats`
|
||||
- `subscriptions`
|
||||
- `user_preferences`
|
||||
|
||||
### 1.5 .env konfigurieren
|
||||
|
||||
```env
|
||||
# server/.env
|
||||
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
|
||||
APPWRITE_PROJECT_ID=deine_projekt_id
|
||||
APPWRITE_API_KEY=dein_api_key
|
||||
APPWRITE_DATABASE_ID=email_sorter_db
|
||||
```
|
||||
|
||||
```env
|
||||
# client/.env
|
||||
VITE_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
|
||||
VITE_APPWRITE_PROJECT_ID=deine_projekt_id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Stripe einrichten
|
||||
|
||||
### 2.1 Account erstellen
|
||||
|
||||
1. Gehe zu [dashboard.stripe.com](https://dashboard.stripe.com)
|
||||
2. Erstelle einen Account
|
||||
3. Wechsle in den **Test Mode** (Toggle oben rechts)
|
||||
|
||||
### 2.2 API Keys kopieren
|
||||
|
||||
1. Gehe zu **Developers** → **API keys**
|
||||
2. Kopiere den **Secret key** (beginnt mit `sk_test_`)
|
||||
|
||||
### 2.3 Produkte erstellen
|
||||
|
||||
Gehe zu **Products** → **Add product**:
|
||||
|
||||
#### Basic Plan
|
||||
- Name: `EmailSorter Basic`
|
||||
- Preis: `9.00 EUR` / Monat
|
||||
- Kopiere die **Price ID** (beginnt mit `price_`)
|
||||
|
||||
#### Pro Plan
|
||||
- Name: `EmailSorter Pro`
|
||||
- Preis: `19.00 EUR` / Monat
|
||||
- Kopiere die **Price ID**
|
||||
|
||||
#### Business Plan
|
||||
- Name: `EmailSorter Business`
|
||||
- Preis: `49.00 EUR` / Monat
|
||||
- Kopiere die **Price ID**
|
||||
|
||||
### 2.4 Webhook einrichten
|
||||
|
||||
1. Gehe zu **Developers** → **Webhooks**
|
||||
2. Klicke auf **Add endpoint**
|
||||
3. URL: `https://deine-domain.de/api/subscription/webhook`
|
||||
- Für lokale Tests: Nutze [Stripe CLI](https://stripe.com/docs/stripe-cli)
|
||||
4. Events auswählen:
|
||||
- `checkout.session.completed`
|
||||
- `customer.subscription.updated`
|
||||
- `customer.subscription.deleted`
|
||||
- `invoice.payment_failed`
|
||||
- `invoice.payment_succeeded`
|
||||
5. Kopiere das **Signing Secret** (beginnt mit `whsec_`)
|
||||
|
||||
### 2.5 Lokaler Webhook-Test mit Stripe CLI
|
||||
|
||||
```bash
|
||||
# Installieren
|
||||
# Windows: scoop install stripe
|
||||
# Mac: brew install stripe/stripe-cli/stripe
|
||||
|
||||
# Login
|
||||
stripe login
|
||||
|
||||
# Webhook forwarden
|
||||
stripe listen --forward-to localhost:3000/api/subscription/webhook
|
||||
```
|
||||
|
||||
### 2.6 .env konfigurieren
|
||||
|
||||
```env
|
||||
# server/.env
|
||||
STRIPE_SECRET_KEY=sk_test_...
|
||||
STRIPE_WEBHOOK_SECRET=whsec_...
|
||||
STRIPE_PRICE_BASIC=price_...
|
||||
STRIPE_PRICE_PRO=price_...
|
||||
STRIPE_PRICE_BUSINESS=price_...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Google OAuth einrichten (Gmail)
|
||||
|
||||
### 3.1 Google Cloud Projekt erstellen
|
||||
|
||||
1. Gehe zu [console.cloud.google.com](https://console.cloud.google.com)
|
||||
2. Erstelle ein neues Projekt (oder wähle ein bestehendes)
|
||||
|
||||
### 3.2 Gmail API aktivieren
|
||||
|
||||
1. Gehe zu **APIs & Services** → **Library**
|
||||
2. Suche nach "Gmail API"
|
||||
3. Klicke auf **Enable**
|
||||
|
||||
### 3.3 OAuth Consent Screen
|
||||
|
||||
1. Gehe zu **APIs & Services** → **OAuth consent screen**
|
||||
2. Wähle **External**
|
||||
3. Fülle aus:
|
||||
- App name: `EmailSorter`
|
||||
- User support email: Deine E-Mail
|
||||
- Developer contact: Deine E-Mail
|
||||
4. **Scopes** hinzufügen:
|
||||
- `https://www.googleapis.com/auth/gmail.modify`
|
||||
- `https://www.googleapis.com/auth/gmail.labels`
|
||||
- `https://www.googleapis.com/auth/userinfo.email`
|
||||
5. **Test users** hinzufügen (während der Entwicklung)
|
||||
|
||||
### 3.4 OAuth Credentials erstellen
|
||||
|
||||
1. Gehe zu **APIs & Services** → **Credentials**
|
||||
2. Klicke auf **Create Credentials** → **OAuth client ID**
|
||||
3. Typ: **Web application**
|
||||
4. Name: `EmailSorter Web`
|
||||
5. **Authorized redirect URIs**:
|
||||
- `http://localhost:3000/api/oauth/gmail/callback` (Entwicklung)
|
||||
- `https://deine-domain.de/api/oauth/gmail/callback` (Produktion)
|
||||
6. Kopiere **Client ID** und **Client Secret**
|
||||
|
||||
### 3.5 .env konfigurieren
|
||||
|
||||
```env
|
||||
# server/.env
|
||||
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
|
||||
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
|
||||
GOOGLE_REDIRECT_URI=http://localhost:3000/api/oauth/gmail/callback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Microsoft OAuth einrichten (Outlook)
|
||||
|
||||
### 4.1 Azure App Registration
|
||||
|
||||
1. Gehe zu [portal.azure.com](https://portal.azure.com)
|
||||
2. Suche nach "App registrations"
|
||||
3. Klicke auf **New registration**
|
||||
4. Name: `EmailSorter`
|
||||
5. Supported account types: **Accounts in any organizational directory and personal Microsoft accounts**
|
||||
6. Redirect URI: `Web` → `http://localhost:3000/api/oauth/outlook/callback`
|
||||
|
||||
### 4.2 Client Secret erstellen
|
||||
|
||||
1. Gehe zu **Certificates & secrets**
|
||||
2. Klicke auf **New client secret**
|
||||
3. Description: `EmailSorter Backend`
|
||||
4. Expires: `24 months`
|
||||
5. Kopiere den **Value** (wird nur einmal angezeigt!)
|
||||
|
||||
### 4.3 API Permissions
|
||||
|
||||
1. Gehe zu **API permissions**
|
||||
2. Klicke auf **Add a permission** → **Microsoft Graph** → **Delegated permissions**
|
||||
3. Füge hinzu:
|
||||
- `Mail.ReadWrite`
|
||||
- `User.Read`
|
||||
- `offline_access`
|
||||
4. Klicke auf **Grant admin consent** (falls möglich)
|
||||
|
||||
### 4.4 .env konfigurieren
|
||||
|
||||
```env
|
||||
# server/.env
|
||||
MICROSOFT_CLIENT_ID=xxx-xxx-xxx
|
||||
MICROSOFT_CLIENT_SECRET=xxx
|
||||
MICROSOFT_REDIRECT_URI=http://localhost:3000/api/oauth/outlook/callback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Mistral AI einrichten
|
||||
|
||||
### 5.1 Account erstellen
|
||||
|
||||
1. Gehe zu [console.mistral.ai](https://console.mistral.ai)
|
||||
2. Erstelle einen Account
|
||||
3. Gehe zu **API Keys**
|
||||
4. Klicke auf **Create new key**
|
||||
5. Kopiere den API Key
|
||||
|
||||
### 5.2 .env konfigurieren
|
||||
|
||||
```env
|
||||
# server/.env
|
||||
MISTRAL_API_KEY=dein_mistral_api_key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Projekt starten
|
||||
|
||||
### 6.1 Dependencies installieren
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd server
|
||||
npm install
|
||||
|
||||
# Frontend
|
||||
cd ../client
|
||||
npm install
|
||||
```
|
||||
|
||||
### 6.2 Environment Files erstellen
|
||||
|
||||
```bash
|
||||
# Server
|
||||
cp server/env.example server/.env
|
||||
# Fülle die Werte aus!
|
||||
|
||||
# Client
|
||||
cp client/env.example client/.env
|
||||
# Fülle die Werte aus!
|
||||
```
|
||||
|
||||
### 6.3 Datenbank initialisieren
|
||||
|
||||
```bash
|
||||
cd server
|
||||
npm run bootstrap:v2
|
||||
```
|
||||
|
||||
### 6.4 Server starten
|
||||
|
||||
```bash
|
||||
# Terminal 1 - Backend
|
||||
cd server
|
||||
npm run dev
|
||||
|
||||
# Terminal 2 - Frontend
|
||||
cd client
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 6.5 Öffnen
|
||||
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **Backend API**: http://localhost:3000
|
||||
- **API Docs**: http://localhost:3000
|
||||
|
||||
---
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
### "APPWRITE_PROJECT_ID is not defined"
|
||||
|
||||
Stelle sicher, dass die `.env` Datei existiert und die Variablen gesetzt sind.
|
||||
|
||||
### "Invalid OAuth redirect URI"
|
||||
|
||||
Die Redirect URI in der OAuth-Konfiguration muss **exakt** mit der in der `.env` übereinstimmen.
|
||||
|
||||
### "Rate limit exceeded"
|
||||
|
||||
- Gmail: Max 10.000 Requests/Tag
|
||||
- Outlook: Max 10.000 Requests/App/Tag
|
||||
|
||||
### "Mistral AI: Model not found"
|
||||
|
||||
Prüfe, ob der API Key gültig ist und das Guthaben ausreicht.
|
||||
|
||||
### "Stripe webhook signature invalid"
|
||||
|
||||
- Nutze das korrekte Webhook Secret (`whsec_...`)
|
||||
- Bei lokalem Test: Nutze die Stripe CLI
|
||||
|
||||
### Microsoft OAuth: "Client credential must not be empty"
|
||||
|
||||
Stelle sicher, dass `MICROSOFT_CLIENT_ID` und `MICROSOFT_CLIENT_SECRET` gesetzt sind. Falls du Outlook nicht nutzen möchtest, kannst du diese leer lassen - der Server startet trotzdem.
|
||||
|
||||
---
|
||||
|
||||
## Checkliste
|
||||
|
||||
- [ ] Appwrite Projekt erstellt
|
||||
- [ ] Appwrite API Key erstellt
|
||||
- [ ] Appwrite Database erstellt
|
||||
- [ ] Bootstrap ausgeführt (`npm run bootstrap:v2`)
|
||||
- [ ] Stripe Account erstellt
|
||||
- [ ] Stripe Produkte erstellt (Basic, Pro, Business)
|
||||
- [ ] Stripe Webhook eingerichtet
|
||||
- [ ] Google OAuth Credentials erstellt (optional)
|
||||
- [ ] Microsoft App Registration erstellt (optional)
|
||||
- [ ] Mistral AI API Key erstellt
|
||||
- [ ] Alle `.env` Dateien konfiguriert
|
||||
- [ ] Server startet ohne Fehler
|
||||
- [ ] Frontend startet ohne Fehler
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
Bei Fragen oder Problemen:
|
||||
- GitHub Issues
|
||||
- support@emailsorter.de
|
||||
Reference in New Issue
Block a user