AirCardIOS/docs/appwrite-console.md

Appwrite-Console: Projekt „AirCard” einrichten

Klickliste für Kenso. Dauer: etwa 5 Minuten. Console: https://appwrite.webklar.com/console

Alles passiert in der bestehenden Organisation. Das Schema (Datenbank, Tabellen cards, gallery, reports mit Spalten und Indizes, Buckets card-images und gallery-images) legt danach das Skript web/scripts/appwrite-setup.mjs an – dafür musst du nichts anklicken.

Hinweis: Das Projekt wurde mit der automatisch generierten ID 6ac2130a00289343d6d5 angelegt (nicht mit einer selbst gewählten ID). Diese ID steht in /home/webklar/apps/.env unter AIRCARD_APPWRITE_PROJECT_ID; das Skript liest sie von dort, der Wert muss beim Aufruf verfügbar sein.

Stand der Einstellungen: Schritt 2 (Web-Plattform aircard-ios.org) ist Voraussetzung, ohne sie lehnt Appwrite die Anfragen der Seite ab. Die Schritte 3 und 4 sind empfohlene Härtung. Ob sie in der Console umgesetzt sind, prüft kein Skript (--check deckt nur das Schema ab: Tabellen, Spalten, Indizes, Buckets). Solange du sie nicht selbst gesetzt hast, läuft das Live-Projekt mit den Appwrite-Standards für Auth und Dienste. Das Schema und die Zeilen-/Dateirechte sind davon unabhängig.

1. Projekt anlegen

1. In der Console anmelden und die bestehende Organisation öffnen.
2. Create project klicken.
3. Name: AirCard.
4. Das Feld Project ID unverändert lassen: Appwrite erzeugt die ID selbst. Nach dem Anlegen steht sie unter Settings (und in der Adresszeile der Console). Sie ist öffentlich, steckt im JavaScript der Seite.
5. Create klicken.

Bei einem Neuaufbau bekommt das neue Projekt eine neue ID. Dann müssen drei Stellen dazu passen: die Traefik-Regel (deploy/traefik/aircard.yml, dort steht die ID im Header(...)), AIRCARD_APPWRITE_PROJECT_ID in /home/webklar/apps/.env und der Standardwert in web/src/account/appwrite.ts.

2. Web-Plattformen eintragen

Projekt AirCard → Overview → Integrations → Platforms → Add platform → Web.

1. Name AirCard Website, Hostname aircard-ios.org → Create.
2. Noch einmal Add platform → Web: Name Entwicklung, Hostname localhost → Create.

3. Auth-Einstellungen (empfohlene Härtung, keine Voraussetzung für den Betrieb)

Linke Leiste → Auth → Settings. Registrieren und Anmelden funktionieren auch mit den Standardwerten; die folgenden Einstellungen begrenzen nur, was Besucher mit dem Projekt anstellen können.

1. Bei Auth methods nur Email/Password eingeschaltet lassen. Ausschalten: Magic URL, Email OTP, Phone, Anonymous (steht dort auch Invites: ebenfalls aus). JWT bleibt an – ohne JWT kann die Community-API (Abschnitt „Community“) die Nutzer nicht prüfen.
2. Session duration: 30 Tage → Update.
3. Max sessions (Sitzungen pro Nutzer): 5 → Update.
4. Limit (Nutzerlimit): 2000 → Update.
5. Password dictionary: einschalten.

Keine E-Mail-Bestätigung nötig, Mindestlänge 8 Zeichen ist Standard – dafür ist nichts einzustellen. Die „Passwort vergessen“-Mail geht über den globalen Server-SMTP (Absender WEBklar), auch dafür ist nichts einzustellen.

4. Nicht benötigte Dienste abschalten (optional)

Linke Leiste → Settings → Reiter Services. Das ist optionale Härtung: Die Website braucht diese Dienste nicht, schadet aber auch nicht, wenn sie an bleiben. Solange du das nicht gemacht hast, sind sie am Live-Projekt an (z. B. antwortet GraphQL).

1. Ausschalten, soweit die Console es dort anbietet: Functions, Sites, Messaging, Teams, GraphQL.
2. Alles andere (Account, Avatars, Databases, Locale, Storage …) bleibt an.

5. API-Key aircard-provision anlegen

Dieser Key gehört nur dem Setup-Skript. Die Website selbst braucht ihn nicht.

1. Overview → Integrations → API keys → Create API key.
2. Name: aircard-provision. Ablauf (Expiration): Never.
3. Unter Scopes genau diese acht ankreuzen (Gruppe Database bzw. Storage):
   • databases.read und databases.write
   • tables.read und tables.write
   • columns.read und columns.write
   • buckets.read und buckets.write
4. Create klicken.
5. Auf der Seite des neuen Keys den Secret-Wert kopieren (Auge-Symbol zum Einblenden, dann kopieren).

Die Indizes der Tabellen gallery und reports legt das Skript mit denselben Scopes an; ein eigener Index-Scope ist nicht nötig.

6. Key auf dem Server eintragen

Der Key gehört in die Datei /home/webklar/apps/.env, nirgendwo sonst.

1. Auf dem Server die Datei öffnen, z. B. nano /home/webklar/apps/.env.

2. Ans Ende springen. Steht der Cursor am Ende der letzten Zeile, einmal Enter drücken, damit die neuen Zeilen in eigenen Zeilen stehen (sonst klebt der erste neue Eintrag an einem bestehenden Wert und macht ihn kaputt). Dann neue Zeilen anfügen, ohne Anführungszeichen und ohne Leerzeichen um das = (die Projekt-ID ist die in Schritt 1 notierte, siehe Hinweis oben):

   AIRCARD_APPWRITE_PROJECT_ID=<Projekt-ID>
   AIRCARD_APPWRITE_API_KEY=<hier den kopierten Secret-Wert einfügen>
   

3. Speichern (in nano: Strg+O, Enter, Strg+X). Andere Zeilen nicht verändern.

4. Den Key möglichst nicht im Chat teilen (wer ihn dort einfügt, gibt ihn in den Verlauf), nicht in Screenshots zeigen und nirgends einchecken. Das Skript bekommt ihn über node --env-file=/home/webklar/apps/.env, dafür muss ihn niemand sonst sehen.

7. Community

Für die Community-Galerie (Tabellen gallery und reports, Bucket gallery-images, API-Dienst aircard-api) sind drei Dinge in der Console nötig. Das Schema dazu legt dasselbe Skript an (node --env-file=/home/webklar/apps/.env web/scripts/appwrite-setup.mjs, vorher mit --check ansehen, was fehlt).

7.1 JWT muss an sein

JWT muss an sein – falls in Schritt 3 ausgeschaltet, wieder einschalten. Auth → Settings → Auth methods → JWT einschalten. Die API prüft damit, wer Veröffentlichen, Zurückziehen oder eine Admin-Aktion auslöst.

7.2 Label admin am eigenen Konto

Das Label admin macht dich zum Admin der Galerie: Die Website zeigt dir dann Ein-/Ausblenden-Knöpfe und den Galerie-Filter „Gemeldet“/„Ausgeblendet“.

1. Linke Leiste → Auth → Users → dein Konto öffnen.
2. Bei Labels den Wert admin eintragen → Update.

7.3 API-Key aircard-api anlegen

Dieser Key gehört nur dem API-Dienst aircard-api, nicht dem Setup-Skript und nicht der Website.

1. Overview → Integrations → API keys → Create API key.

2. Name: aircard-api. Ablauf (Expiration): Never.

3. Unter Scopes genau diese vier ankreuzen:

   • documents.read und documents.write
   • files.read und files.write

   Die Console beschriftet die Zeilen-Scopes mit documents.*; das sind dieselben wie die rows.read/rows.write der Appwrite-API (Tabellen heißen dort Zeilen). Einen Eintrag rows.* gibt es in der Console nicht.

4. Create klicken und auf der Seite des Keys den Secret-Wert kopieren.

5. Auf dem Server den Wert verdeckt in die .env schreiben. Der Befehl fragt den Wert ohne Anzeige ab (read -rs), schreibt bei leerer Eingabe nichts, beginnt mit einem Zeilenumbruch (so klebt die Zeile nie an einer letzten Zeile ohne Umbruch) und zeigt den Key nirgends an:

   read -rs -p "AIRCARD_API_KEY: " K; echo; if [ -n "$K" ]; then printf '\nAIRCARD_API_KEY=%s\n' "$K" >> /home/webklar/apps/.env; else echo "Leer – nichts geschrieben."; fi; unset K
   

   Den Wert nicht im Chat teilen. Wurde der Provisioning-Key aus Schritt 5 einmal im Chat geteilt, ihn in der Console unter API keys löschen und bei Bedarf neu anlegen.

8. Bescheid geben

Schreib Claude „Console fertig“. Danach legt Claude Datenbank aircard, die Tabellen cards, gallery, reports (mit Spalten und Indizes) und die Buckets card-images, gallery-images mit dem Skript an und prüft sie. Für die Community-Galerie schreib zusätzlich „Label und Key sind gesetzt“.