eship/setup/USERS_COLLECTION_SETUP.md

Users Collection Setup & Permissions

Diese Anleitung erklärt, wie du die users Collection in Appwrite einrichtest und die richtigen Permissions setzt.

Problem: 401 Unauthorized

Wenn du beim Erstellen eines User-Dokuments einen 401 Unauthorized Fehler bekommst, bedeutet das, dass die Permissions der Collection nicht richtig gesetzt sind.

Lösung: Collection erstellen und Permissions setzen

Schritt 1: Collection-ID ermitteln oder erstellen

Option A: Collection bereits vorhanden

Prüfe, ob die Collection bereits existiert:

cd Server
appwrite login
appwrite databases list-collections --database-id eship-db

Suche nach einer Collection mit dem Namen "users" oder einer ID, die du verwenden möchtest.

Option B: Collection erstellen

Falls die Collection nicht existiert, erstelle sie:

appwrite databases create-collection \
  --database-id eship-db \
  --collection-id users \
  --name "Users"

Wichtig: Notiere dir die $id der erstellten Collection. Falls die Collection-ID nicht "users" ist, musst du sie in der .env Datei setzen:

VITE_APPWRITE_USERS_COLLECTION_ID=<deine-collection-id>

Schritt 2: Attribute hinzufügen

Die Collection braucht ein user_name Feld (String):

appwrite databases create-string-attribute \
  --database-id eship-db \
  --collection-id users \
  --key user_name \
  --size 255 \
  --required true

Wichtig: Warte, bis das Attribute erstellt wurde (Status: "available"). Das kann einige Sekunden dauern.

Schritt 3: Permissions setzen

Das ist der wichtigste Schritt! Die Collection muss erlauben, dass:

• Authentifizierte User Dokumente lesen können
• Authentifizierte User Dokumente erstellen können (für ihr eigenes Dokument)

Über die Appwrite-Konsole (empfohlen)

1. Öffne die Appwrite-Konsole: https://appwrite.webklar.com
2. Gehe zu: Databases → eship-db → users Collection
3. Klicke auf Settings → Permissions
4. Füge folgende Permissions hinzu:

Create Permission:

• Role: users
• Erlaube: create

Read Permission:

• Role: users
• Erlaube: read

Update Permission (optional, falls du Updates brauchst):

• Role: users
• Erlaube: update

Delete Permission (optional):

• Role: users
• Erlaube: delete

Über die CLI

# Create Permission
appwrite databases create-collection-create-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

# Read Permission
appwrite databases create-collection-read-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

# Optional: Update Permission
appwrite databases create-collection-update-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

# Optional: Delete Permission
appwrite databases create-collection-delete-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

Hinweis: Die CLI-Befehle können je nach Appwrite-Version variieren. Wenn sie nicht funktionieren, verwende die Web-Konsole.

Schritt 4: Document-ID-Permissions

Da wir die Auth-User-ID als Document-ID verwenden, muss Appwrite erlauben, dass User ihre eigene Document-ID verwenden können.

In der Appwrite-Konsole:

1. Gehe zu: Databases → eship-db → users → Settings
2. Stelle sicher, dass "Allow users to specify their own document IDs" aktiviert ist
   • Oder setze: "Document ID Generation" auf "User provided"

Schritt 5: Überprüfung

Nach dem Setup sollte:

• ✅ Ein eingeloggter User Dokumente lesen können
• ✅ Ein eingeloggter User sein eigenes Dokument erstellen können (mit seiner Auth-User-ID als Document-ID)

Häufige Probleme

Problem: "Collection not found"

Lösung: Prüfe, ob die Collection-ID korrekt ist:

appwrite databases list-collections --database-id eship-db

Stelle sicher, dass VITE_APPWRITE_USERS_COLLECTION_ID in der .env die richtige ID enthält.

Problem: "Attribute not found"

Lösung: Prüfe, ob das user_name Attribute existiert:

appwrite databases list-attributes \
  --database-id eship-db \
  --collection-id users

Problem: "Permission denied"

Lösung: Stelle sicher, dass die Permissions für die Rolle users gesetzt sind. In der Appwrite-Konsole:

• Gehe zu Settings → Permissions
• Prüfe, ob create und read für users aktiviert sind

Alternative: Restriktivere Permissions (sicherer)

Falls du sicherer sein möchtest, dass User nur ihr eigenes Dokument lesen/erstellen können:

1. In der Appwrite-Konsole: Gehe zu Settings → Permissions
2. Verwende Custom Permissions mit Filtern:
   • Read: $userId = request.auth.userId
   • Create: $userId = request.auth.userId
   • Update: $userId = request.auth.userId

Dies stellt sicher, dass User nur Zugriff auf ihr eigenes Dokument haben.

Nächste Schritte

Nach dem Setup:

1. Lade die Web-App neu
2. Logge dich ein
3. Du solltest den Welcome-Screen sehen
4. Beim Klick auf "Jetzt starten" sollte das User-Dokument erstellt werden (kein 401-Fehler mehr)