diff --git a/docs/PRODUCTION_LAUNCH.md b/docs/PRODUCTION_LAUNCH.md new file mode 100644 index 000000000..d91a108cb --- /dev/null +++ b/docs/PRODUCTION_LAUNCH.md @@ -0,0 +1,296 @@ +# Production Launch Guide - mana.how + +Diese Anleitung beschreibt alle Schritte um die Staging-Umgebung zur Production zu machen. + +**Server:** 46.224.108.214 (Hetzner) +**Domain:** mana.how + +--- + +## Schritt 1: DNS-Einträge anlegen + +Bei eurem DNS-Provider (wo `mana.how` registriert ist) folgende A-Records anlegen: + +### Erforderliche DNS-Einträge + +| Subdomain | Typ | Ziel | TTL | +|-----------|-----|------|-----| +| `@` (root) | A | 46.224.108.214 | 300 | +| `www` | A | 46.224.108.214 | 300 | +| `auth` | A | 46.224.108.214 | 300 | +| `chat` | A | 46.224.108.214 | 300 | +| `chat-api` | A | 46.224.108.214 | 300 | +| `todo` | A | 46.224.108.214 | 300 | +| `todo-api` | A | 46.224.108.214 | 300 | +| `calendar` | A | 46.224.108.214 | 300 | +| `calendar-api` | A | 46.224.108.214 | 300 | +| `clock` | A | 46.224.108.214 | 300 | +| `clock-api` | A | 46.224.108.214 | 300 | + +**Alternative mit Wildcard:** +| Subdomain | Typ | Ziel | TTL | +|-----------|-----|------|-----| +| `@` (root) | A | 46.224.108.214 | 300 | +| `*` | A | 46.224.108.214 | 300 | + +> **Hinweis:** Nach dem Anlegen kann es bis zu 24h dauern bis die DNS-Einträge weltweit propagiert sind. In der Praxis meist schneller. + +### DNS prüfen + +```bash +# Prüfen ob DNS korrekt ist +dig mana.how +short +dig auth.mana.how +short +dig chat.mana.how +short +# Sollte jeweils 46.224.108.214 zurückgeben +``` + +--- + +## Schritt 2: Server vorbereiten + +SSH auf den Server: + +```bash +ssh -i ~/.ssh/hetzner_deploy_key deploy@46.224.108.214 +``` + +### 2.1 Backup der aktuellen Staging-Daten (optional aber empfohlen) + +```bash +cd ~/manacore-staging + +# Datenbank-Backup erstellen +docker compose exec -T postgres pg_dumpall -U postgres > ~/backup_$(date +%Y%m%d_%H%M%S).sql + +echo "Backup erstellt: ~/backup_*.sql" +``` + +### 2.2 Staging Container stoppen + +```bash +cd ~/manacore-staging +docker compose down +``` + +--- + +## Schritt 3: Production Konfiguration deployen + +### 3.1 Verzeichnis umbenennen (optional) + +```bash +# Von staging zu production umbenennen +mv ~/manacore-staging ~/manacore-production +cd ~/manacore-production +``` + +### 3.2 Production docker-compose kopieren + +Vom lokalen Rechner: + +```bash +# Aus dem Repo-Root +scp -i ~/.ssh/hetzner_deploy_key \ + docker-compose.production.yml \ + deploy@46.224.108.214:~/manacore-production/docker-compose.yml +``` + +### 3.3 Production Caddyfile kopieren + +```bash +scp -i ~/.ssh/hetzner_deploy_key \ + docker/caddy/Caddyfile.production \ + deploy@46.224.108.214:~/Caddyfile +``` + +### 3.4 Caddy neu laden + +Auf dem Server: + +```bash +# Caddy Config neu laden +docker exec caddy caddy reload --config /etc/caddy/Caddyfile + +# Prüfen ob Caddy läuft +docker logs caddy --tail 20 +``` + +--- + +## Schritt 4: Environment Variables anpassen + +Auf dem Server die `.env` Datei anpassen: + +```bash +cd ~/manacore-production +nano .env +``` + +Die bestehenden Staging-Werte können bleiben. Nur sicherstellen dass: + +```env +NODE_ENV=production + +# Diese Werte bleiben gleich (Staging Secrets weiterverwenden): +POSTGRES_PASSWORD= +REDIS_PASSWORD= +JWT_SECRET= +JWT_PUBLIC_KEY= +JWT_PRIVATE_KEY= +SUPABASE_URL= +SUPABASE_ANON_KEY= +SUPABASE_SERVICE_ROLE_KEY= +AZURE_OPENAI_ENDPOINT= +AZURE_OPENAI_API_KEY= +``` + +--- + +## Schritt 5: Container starten + +```bash +cd ~/manacore-production + +# Images pullen +docker compose pull + +# Container starten +docker compose up -d + +# Status prüfen +docker compose ps +``` + +--- + +## Schritt 6: Health Checks + +```bash +# Alle Services prüfen +curl -s http://localhost:3001/api/v1/health # Auth +curl -s http://localhost:5173/health # Dashboard +curl -s http://localhost:3000/health # Chat Web +curl -s http://localhost:3002/api/v1/health # Chat API +curl -s http://localhost:5188/health # Todo Web +curl -s http://localhost:3018/api/health # Todo API +curl -s http://localhost:5186/health # Calendar Web +curl -s http://localhost:3016/api/v1/health # Calendar API +curl -s http://localhost:5187/health # Clock Web +curl -s http://localhost:3017/api/v1/health # Clock API +``` + +--- + +## Schritt 7: SSL-Zertifikate (automatisch) + +Caddy holt sich automatisch Let's Encrypt Zertifikate sobald die DNS-Einträge korrekt sind. + +Prüfen: + +```bash +# Logs prüfen auf Certificate-Meldungen +docker logs caddy 2>&1 | grep -i "certificate\|tls" + +# Oder direkt testen +curl -I https://mana.how +``` + +--- + +## Schritt 8: Finale Tests + +Im Browser testen: + +| URL | Erwartet | +|-----|----------| +| https://mana.how | Dashboard Login | +| https://auth.mana.how/api/v1/health | `{"status":"ok"}` | +| https://chat.mana.how | Chat App Login | +| https://todo.mana.how | Todo App Login | +| https://calendar.mana.how | Calendar App Login | +| https://clock.mana.how | Clock App Login | + +--- + +## Troubleshooting + +### Container startet nicht + +```bash +# Logs anschauen +docker compose logs + +# Beispiel +docker compose logs mana-core-auth +docker compose logs chat-backend +``` + +### DNS nicht propagiert + +```bash +# Verschiedene DNS-Server testen +dig @8.8.8.8 mana.how +short # Google DNS +dig @1.1.1.1 mana.how +short # Cloudflare DNS +``` + +### SSL-Zertifikat Fehler + +```bash +# Caddy Logs prüfen +docker logs caddy --tail 100 + +# Caddy neu starten +docker restart caddy +``` + +### Datenbank Verbindungsfehler + +```bash +# Postgres prüfen +docker compose exec postgres psql -U postgres -l + +# Datenbanken anzeigen +docker compose exec postgres psql -U postgres -c "\l" +``` + +--- + +## Rollback zu Staging + +Falls etwas schief geht: + +```bash +cd ~/manacore-production +docker compose down + +# Alte Staging docker-compose wiederherstellen +# (müsste vorher gesichert werden) + +# Caddyfile zurück auf staging +scp -i ~/.ssh/hetzner_deploy_key \ + docker/caddy/Caddyfile.staging \ + deploy@46.224.108.214:~/Caddyfile + +docker exec caddy caddy reload --config /etc/caddy/Caddyfile +docker compose up -d +``` + +--- + +## Zusammenfassung der URLs + +Nach erfolgreichem Launch: + +| App | URL | +|-----|-----| +| **Dashboard** | https://mana.how | +| **Auth API** | https://auth.mana.how | +| **Chat** | https://chat.mana.how | +| **Chat API** | https://chat-api.mana.how | +| **Todo** | https://todo.mana.how | +| **Todo API** | https://todo-api.mana.how | +| **Calendar** | https://calendar.mana.how | +| **Calendar API** | https://calendar-api.mana.how | +| **Clock** | https://clock.mana.how | +| **Clock API** | https://clock-api.mana.how | diff --git a/docs/URL_SCHEMA.md b/docs/URL_SCHEMA.md new file mode 100644 index 000000000..fc0a1fd3e --- /dev/null +++ b/docs/URL_SCHEMA.md @@ -0,0 +1,150 @@ +# URL Schema - mana.how + +This document defines the URL schema for all mana.how subdomains. + +## Naming Convention + +- **Landing Pages**: Plural form (e.g., `calendars.mana.how`) +- **Web Apps**: Singular form (e.g., `calendar.mana.how`) +- **APIs**: Singular + `-api` suffix (e.g., `calendar-api.mana.how`) +- **Short URLs**: Redirect to Web Apps for convenience + +--- + +## Complete URL Mapping + +### Core Apps + +| App | Landing Page | Web App | API | +|-----|--------------|---------|-----| +| **Calendar** | calendars.mana.how | calendar.mana.how | calendar-api.mana.how | +| **Clock** | clocks.mana.how | clock.mana.how | clock-api.mana.how | +| **Todo** | todos.mana.how | todo.mana.how | todo-api.mana.how | +| **Contacts** | contacts.mana.how | contact.mana.how | contact-api.mana.how | +| **Chat** | chats.mana.how | chat.mana.how | chat-api.mana.how | +| **Picture** | pictures.mana.how | picture.mana.how | picture-api.mana.how | +| **Zitare** | zitares.mana.how | zitare.mana.how | zitare-api.mana.how | + +### Platform + +| Service | URL | +|---------|-----| +| **Main Dashboard** | mana.how | +| **Dashboard App** | app.mana.how | +| **Auth Service** | auth.mana.how | + +--- + +## Short URL Redirects + +Convenience redirects for quick access to Web Apps: + +| Short URL | Redirects To | +|-----------|--------------| +| cal.mana.how | calendar.mana.how | +| clok.mana.how | clock.mana.how | +| con.mana.how | contact.mana.how | +| pic.mana.how | picture.mana.how | +| zit.mana.how | zitare.mana.how | + +--- + +## Hosting + +### Landing Pages (Astro Static Sites) + +**Platform:** Cloudflare Pages + +Landing pages are deployed via Cloudflare Pages using Wrangler CLI: + +```bash +# Deploy individual landing page +pnpm deploy:landing:calendar +pnpm deploy:landing:clock +pnpm deploy:landing:todo +pnpm deploy:landing:contacts +pnpm deploy:landing:chat +pnpm deploy:landing:picture +pnpm deploy:landing:zitare + +# Deploy all landing pages +pnpm deploy:landing:all +``` + +**Cloudflare Project Names:** + +| App | Cloudflare Project | Custom Domain | +|-----|-------------------|---------------| +| Calendar | calendars-landing | calendars.mana.how | +| Clock | clocks-landing | clocks.mana.how | +| Todo | todos-landing | todos.mana.how | +| Contacts | contacts-landing | contacts.mana.how | +| Chat | chats-landing | chats.mana.how | +| Picture | pictures-landing | pictures.mana.how | +| Zitare | zitares-landing | zitares.mana.how | + +### Web Apps & APIs + +**Platform:** Hetzner Server (46.224.108.214) via Docker + Caddy + +See [PRODUCTION_LAUNCH.md](./PRODUCTION_LAUNCH.md) for deployment details. + +--- + +## DNS Configuration + +All subdomains point to Hetzner server, except landing pages which use Cloudflare: + +### A Records (Hetzner - Web Apps & APIs) + +``` +calendar.mana.how A 46.224.108.214 +calendar-api.mana.how A 46.224.108.214 +clock.mana.how A 46.224.108.214 +clock-api.mana.how A 46.224.108.214 +todo.mana.how A 46.224.108.214 +todo-api.mana.how A 46.224.108.214 +contact.mana.how A 46.224.108.214 +contact-api.mana.how A 46.224.108.214 +chat.mana.how A 46.224.108.214 +chat-api.mana.how A 46.224.108.214 +picture.mana.how A 46.224.108.214 +picture-api.mana.how A 46.224.108.214 +zitare.mana.how A 46.224.108.214 +zitare-api.mana.how A 46.224.108.214 +app.mana.how A 46.224.108.214 +auth.mana.how A 46.224.108.214 +``` + +### CNAME Records (Cloudflare - Landing Pages) + +``` +calendars.mana.how CNAME calendars-landing.pages.dev +clocks.mana.how CNAME clocks-landing.pages.dev +todos.mana.how CNAME todos-landing.pages.dev +contacts.mana.how CNAME contacts-landing.pages.dev +chats.mana.how CNAME chats-landing.pages.dev +pictures.mana.how CNAME pictures-landing.pages.dev +zitares.mana.how CNAME zitares-landing.pages.dev +``` + +### Short URL Redirects (Cloudflare Redirect Rules or CNAME) + +``` +cal.mana.how → 301 redirect to calendar.mana.how +clok.mana.how → 301 redirect to clock.mana.how +con.mana.how → 301 redirect to contact.mana.how +pic.mana.how → 301 redirect to picture.mana.how +zit.mana.how → 301 redirect to zitare.mana.how +``` + +--- + +## Adding a New App + +1. Create landing page in `apps/{app}/apps/landing/` +2. Add `wrangler.toml` with project name `{apps}-landing` +3. Add deploy script to root `package.json` +4. Create Cloudflare Pages project: `npx wrangler pages project create {apps}-landing` +5. Add custom domain in Cloudflare dashboard +6. Update this documentation