mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 18:41:08 +02:00
docs: add production launch guide and URL schema
- PRODUCTION_LAUNCH.md: Step-by-step guide for deploying to mana.how - URL_SCHEMA.md: Define naming conventions for subdomains - Landing pages: plural (calendars.mana.how) - Web apps: singular (calendar.mana.how) - APIs: singular + -api suffix Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Till-JS
parent
5e54bcc5db
commit
447dfe276e
2 changed files with 446 additions and 0 deletions
296
docs/PRODUCTION_LAUNCH.md
Normal file
296
docs/PRODUCTION_LAUNCH.md
Normal file
|
|
@ -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=<behalten>
|
||||
REDIS_PASSWORD=<behalten>
|
||||
JWT_SECRET=<behalten>
|
||||
JWT_PUBLIC_KEY=<behalten>
|
||||
JWT_PRIVATE_KEY=<behalten>
|
||||
SUPABASE_URL=<behalten>
|
||||
SUPABASE_ANON_KEY=<behalten>
|
||||
SUPABASE_SERVICE_ROLE_KEY=<behalten>
|
||||
AZURE_OPENAI_ENDPOINT=<behalten>
|
||||
AZURE_OPENAI_API_KEY=<behalten>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 <service-name>
|
||||
|
||||
# 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 |
|
||||
150
docs/URL_SCHEMA.md
Normal file
150
docs/URL_SCHEMA.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue