# playground

Experimentier-Site auf [playground.schwenk.online](https://playground.schwenk.online): statisches HTML, Inhalte per `@cursor` in Gitea-Issues, Auto-Deploy per Push-Webhook.

## Wie es funktioniert

1. Issue in Gitea öffnen, z. B. *„Onepager: Thema XY“*
2. Kommentar **oder** Issue-Titel/-Body mit `@cursor`, z. B. *„@cursor recherchiere zu Thema XY …“*
3. Gitea Action ([cursor-gitea-agent](https://gitea.schwenk.online/froxxxy/cursor-gitea-agent)) committet nach `public/<slug>/` auf `main`
4. Push-Webhook triggert `git pull` → nginx liefert statische Seiten aus

**Apps** (npm, Docker, DB): Code unter `apps/<slug>/`, Deploy nur manuell — siehe unten.

Content-Konventionen: siehe [SOUL.md](SOUL.md).

## Repo-Layout

```
public/           # Webroot (statisch, auto-deploy per Push-Webhook)
apps/             # Web-Apps mit Build/Docker (manueller Deploy-Workflow)
nginx/            # nginx-Konfiguration
hooks/            # Webhook-Skripte (nur git pull für static)
deploy-hook/      # Webhook-Container
scripts/          # deploy-app.sh (Gitea Action auf boka)
compose.yml       # nginx + deploy-hook + optionale App-Profiles
.gitea/workflows/
  cursor.yml      # @cursor in Issues
  deploy-app.yml  # manuell: Build + docker compose --profile
```

Auf boka ist `/home/frank/playground.schwenk.online` ein **Git-Clone** dieses Repos.

## Gitea (einmalig)

1. **`cursor`-Bot** als Collaborator zum Repo hinzufügen
2. **Repo-Secrets** (Namen ohne `GITEA_`-Prefix):
   - `CURSOR_API_KEY` — Cursor API key
   - `CURSOR_BOT_TOKEN` — Gitea API token des `cursor`-Users
   - `DEPLOY_GIT_TOKEN` — für App-Deploy-Workflow (`git pull` auf boka); kann identisch mit Bot-Token sein
   - `DEPLOY_ROOT` (optional) — Default `/home/frank/playground.schwenk.online`
3. **Push-Webhook** (Repo → Einstellungen → Webhooks):
   - URL: `https://playground.schwenk.online/hooks/deploy`
   - Content type: `application/json`
   - Event: **Push**
   - Secret: gleicher Wert wie `WEBHOOK_SECRET` in `.env` auf boka

## boka Bootstrap (einmalig)

**Automatisch** (von Arch-Dev-Rechner):

```bash
./scripts/bootstrap-boka.sh
```

Erzeugt `.env` mit zufälligem `WEBHOOK_SECRET` (Wert in der Ausgabe — für Gitea-Webhook eintragen).

**Manuell:**
ssh frank-schwenk.de

# App-Verzeichnis (Compose + Config)
git clone ssh://git@gitea.schwenk.online:2222/froxxxy/playground.git \
  /home/frank/playground.schwenk.online
cd /home/frank/playground.schwenk.online

cp .env.example .env
# WEBHOOK_SECRET, DEPLOY_GIT_TOKEN, HOST_UID/HOST_GID eintragen

docker compose up -d --build
```

(Manueller Pfad endet oben bei `docker compose up -d --build`.)

**Deploy-Token:** In Gitea einen read-only Token anlegen (oder dedizierten Deploy-User), nur für `git pull` im Container.

DNS: `playground.schwenk.online` → boka (A-Record).

## Lokaler Smoke-Test (optional)

Ohne Traefik — nur prüfen ob nginx die leere `public/` ausliefert:

```bash
docker run --rm -p 8080:80 \
  -v "$(pwd)/public:/usr/share/nginx/html:ro" \
  -v "$(pwd)/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro" \
  -v "$(pwd)/nginx/security-headers.conf:/etc/nginx/conf.d/security-headers.conf:ro" \
  nginx
# curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/  → 404 (kein index.html, erwartet)
```

## Manuelles Deploy (Fallback)

```bash
ssh frank-schwenk.de
cd /home/frank/playground.schwenk.online
git pull
docker compose up -d
```

## Beispiel-URL nach erstem Onepager

`https://playground.schwenk.online/thema-xy/` — wenn Cursor `public/thema-xy/index.html` angelegt hat.

## Apps deployen (manuell)

Für `apps/<slug>/` mit npm/Docker/DB — **nicht** über den Push-Webhook.

1. `@cursor` legt App unter `apps/<slug>/` an + `compose.yml`-Profile (Vorlage: `apps/_template/`)
2. Push auf `main` (Webhook zieht nur Dateien, baut die App nicht)
3. Gitea → Actions → **Deploy App (manual)** → Run workflow → `app` = `<slug>`

Der Workflow ruft `scripts/deploy-app.sh` auf boka auf: `git pull`, optional `npm ci && build`, dann `docker compose --profile <slug> up -d --build`.

**Nur manuell** — kein Push-, kein Issue-Trigger. Optional pro App: `.gitea/workflows/deploy-<slug>.yml` aus `apps/_template/workflow-deploy.yml.template` (ebenfalls nur `workflow_dispatch`).