# Self-hosted deploy: Gitea + Caddy + EMS (`/opt/ems-deploy`)

Runbook pro **single-node Debian**, **Docker Compose**, **Gitea Actions** bez Kubernetes. Doplňuje konkrétní stav serveru (ZFS, `zfs` storage driver, Caddy na hostu, Gitea v `/opt/gitea-stack`).

---

## 1. Co kde běží

| Oblast | Cesta / adresa | Poznámka |
|--------|----------------|----------|
| Gitea (HTTP) | `https://git.vojacek.eu` → Caddy → `127.0.0.1:3000` | Gitea publikuje HTTP jen na loopback. |
| Gitea (Git SSH) | `git.vojacek.eu:2222` → kontejner `:22` | Host SSH zůstává na `:22`. V `app.ini`: `START_SSH_SERVER = false` (kvůli SSH v base image). |
| Gitea stack | `/opt/gitea-stack` | `postgres`, `gitea`, `gitea-runner`; vlastní `docker-compose` + `.env`. |
| Gitea runner | stejný stack | `act_runner` s přepsaným `entrypoint`/`command`; registrace ručně → `runner/runner.json`. |
| EMS deploy | `/opt/ems-deploy` | Oddělený Compose projekt od Gitea. |
| EMS checkout | `/opt/ems-deploy/app` | Git clone stejného repa jako v Gitea. |
| EMS Compose (runtime) | `/opt/ems-deploy/docker-compose.yml` | Kopíruje se ze `app/deploy/docker-compose.yml` při každém deployi (`deploy.sh`). |
| EMS secrets | `/opt/ems-deploy/.env` | **Není v gitu**; vzor `.env.example` v repu. |

**PostgREST v produkčním `deploy/docker-compose.yml`:** služba naslouchá v **Docker síti** na `:3000`, **bez** mapování na host — frontend v kontejneru volá `postgrest:3000`. Tím se vyhne kolizi s Gitea na hostovém `127.0.0.1:3000`. Pokud někdy přidáš `ports` pro ladění, použij jiný host port než 3000.

---

## 2. Architektonický verdikt

**Směr (push → Actions → skript na hostu → `docker compose build && up`) je správný** pro cíl „jeden server, žádný registry, žádný DinD“.

**Tvrdá fakta / rizika**

1. **Job Gitea Actions neběží na hostu**, ale ve **job kontejneru** (Docker executor). Kroky typu `run: /opt/ems-deploy/deploy.sh` tedy **neuvidí** hostovské cesty, dokud je nepřimountuješ do job kontejneru a nepřidáš je do `valid_volumes` u runneru.
2. **Mount Docker socketu do jobu = plná moc nad hostovským Dockerem** (ekvivalent root pro kontejnery). Je to běžný pattern u self-hosted runnerů; bezpečnost = důvěra k přístupu do repa a k labelům runneru, ne veřejný runner.
3. **`docker: command not found` v jobu** je očekávané u defaultního image — buď použij image s `docker` + `docker compose`, nebo vůbec nevolaj docker uvnitř jobu (u tebe stačí spustit `deploy.sh`, který mluví s hostovským daemonem přes socket).
4. **ZFS + Docker `zfs` driver:** snapshoty a `zfs list` rostou s image vrstvami; `deploy.sh` už dělá `docker image prune -f` (dangling). Hlídej místo na poolu a případně periodický `docker system prune` (opatrně — nesmí mazat věci, co potřebuješ).
5. **`git reset --hard origin/main`:** rychlé a deterministické; jakýkoli lokální drift v `/opt/ems-deploy/app` na serveru se **ztratí**. Na produkční app adresář nesahat ručně — vždy přes git + deploy.
6. **Dvě síťě:** `ems_net` vs `gitea_net` — služby se defaultně nevidí; pro EMS to obvykle nevadí. Integrovat Gitea DB s EMS nechceš.

---

## 3. Tok deploye (cílový)

```mermaid
flowchart LR
  dev[Dev laptop] -->|git push| gitea[Gitea main]
  gitea --> act[Gitea Actions]
  act --> runner[act_runner + Docker]
  runner --> ci[migration-check validate]
  ci -->|needs ok| job[deploy job + /opt mount]
  job --> sh[deploy.sh]
  sh --> git[git fetch / reset main]
  sh --> sync[install compose.yml]
  sh --> fly[flyway validate then migrate]
  sh --> dc["docker compose build && up -d"]
  dc --> hostd[Host Docker Engine]
  hostd --> ems[EMS stack]
```

1. Vývoj lokálně, merge do `main`, push na `git.vojacek.eu:2222`.
2. Workflow `.gitea/workflows/deploy.yml` (label `self-hosted`) spustí job.
3. Job kontejner má `docker.sock` a rw mount `/opt/ems-deploy`; nainstaluje `git`, `bash`, `docker-cli`, `docker-cli-compose` (Alpine).
4. `/opt/ems-deploy/deploy.sh`: `flock`, `git` v `app/`, sync `docker-compose.yml`, `docker compose config`, **`flyway validate`** (soubory vs `flyway_schema_history` na DB), **`flyway migrate`**, `build`, `up -d`, `image prune -f`.

Build probíhá na **hostovském** Dockeru (stejný daemon jako Gitea stack), bez DinD.

---

## 4. Bootstrap serveru (jednorázově)

Přesně podle hlavičky v `deploy/deploy.sh`:

```bash
sudo mkdir -p /opt/ems-deploy/app
sudo chown -R "$USER:$USER" /opt/ems-deploy
git clone ssh://git@git.vojacek.eu:2222/vojacekd/ems.git /opt/ems-deploy/app
cp /opt/ems-deploy/app/.env.example /opt/ems-deploy/.env
chmod 600 /opt/ems-deploy/.env
# doplnit secrets / DB / JWT / …
install -m 755 /opt/ems-deploy/app/deploy/deploy.sh /opt/ems-deploy/deploy.sh
/opt/ems-deploy/deploy.sh
```

Uživatel, pod kterým běží runnerův job (root v Alpine job image), musí mít právo číst `.env`, psát do `app/.git` a volat Docker. Typicky runner běží jako root → ověř oprávnění na `/opt/ems-deploy`.

---

## 5. Gitea runner — nutná úprava `config.yaml`

Aby job směl přimountovat hostové cesty, v `runner/config.yaml` (na serveru v `/opt/gitea-stack/runner/config.yaml`) **musí** být v `container.valid_volumes` povolené alespoň:

```yaml
container:
  network: host
  privileged: false
  valid_volumes:
    - /opt/ems-deploy
    - /var/run/docker.sock
```

Bez toho Actions mounty odmítnou / job spadne. Po změně restart runner kontejneru.

`labels` při registraci runneru musí odpovídat `runs-on` ve workflow (např. výchozí `self-hosted`).

---

## 6. Caddy a EMS (až bude veřejná doména)

Gitea blok v Caddyfile zůstává. Pro EMS přidej **samostatný** site blok, např.:

```caddy
ems.vojacek.eu {
  encode gzip
  @api path /rest*
  handle @api {
    uri strip_prefix /rest
    reverse_proxy 127.0.0.1:8080
  }
  handle {
    reverse_proxy 127.0.0.1:8080
  }
}
```

**Upřesnění podle skutečného nginx ve frontend image:** pokud API jde přes stejný origin a path `/rest`, výše může stačit jeden `reverse_proxy` na `127.0.0.1:8080` bez stripu — ověř v `frontend` konfiguraci. Pro PostgREST OpenAPI nastav v `.env` / `PGRST_OPENAPI_SERVER_PROXY_URI` veřejnou bázi URL.

Produkční compose mapuje frontend na **`127.0.0.1:8080`**, backend na **`127.0.0.1:8000`**.

---

## 7. CI a deploy (jeden workflow)

| Soubor | Účel |
|--------|------|
| `.gitea/workflows/deploy.yml` | **`migration-check`** na `pull_request` a `push` (`main`, `feature/**`): checkout přes `git fetch` (bez Node), skript **neměnnosti** `scripts/ci_check_migration_immutability.sh` (proti `origin/main` nebo base SHA u PR), **`flyway validate`** proti DB z JDBC (viz secrets). **`deploy`** jen při `push` na `main`, **`needs: migration-check`** — pak `/opt/ems-deploy/deploy.sh`. |

**Gitea secrets (repo):**

| Secret | Účel |
|--------|------|
| `EMS_CI_FLYWAY_URL` | JDBC na staging / sdílenou DB s aktuální `flyway_schema_history` (např. `jdbc:postgresql://host:5432/ems`). Pokud **není** nastaveno, krok remote validate se **přeskočí** (varování v logu); immutability check pořád běží. |
| `EMS_CI_FLYWAY_USER` / `EMS_CI_FLYWAY_PASSWORD` | Volitelně, pokud nejsou v URL. |

Job **nemá** `container:` — potřebuje hostovský `docker` + `git` (stejně jako deploy). Runner: `valid_volumes` pro `/var/run/docker.sock` (sekce 5).

**Lokálně před commitem:** z kořene repa s rozjetým Postgres z `docker-compose.yml` a aspoň jednou proběhlým migrate spusť `./scripts/flyway_validate_local.sh` (`flyway validate` vůči lokální DB).

**Flyway `validate` vs `migrate`:** `validate` nekontroluje „dry-run“ celého SQL nové pending migrace; ověří hlavně shodu **již zapsaných** řádků ve `flyway_schema_history` se soubory v repu (checksumy atd.) — proto musí běžet proti **běžící** DB. `migrate` teprve aplikuje pending skripty.

`workflow_dispatch` na větvi `main` spustí `migration-check` a potom i **`deploy`** (stejná podmínka jako u push na `main`).

---

## 8. Co záměrně neděláme (zatím)

- Privátní Docker registry na stejném stroji.
- Buildkit cache export / remote cache.
- k3s/Kubernetes.
- Spouštění `docker compose` uvnitř jobu bez přístupu k **jednomu** hostovskému daemonu (tj. bez soku bys musel do DinD nebo remote docker).

---

## 9. Rychlá kontrola po deployi

```bash
docker compose -f /opt/ems-deploy/docker-compose.yml --env-file /opt/ems-deploy/.env ps
curl -sf http://127.0.0.1:8000/docs >/dev/null && echo backend OK
curl -sf http://127.0.0.1:8080/ >/dev/null && echo frontend OK
```

---

## 10. Reset DB a obnova z dumpu

Kompletní postup (zastavení služeb, `down`, smazání volume `db_data`, jen `db`, `import_ems_db.sh`, Flyway, `up`): **[database-reset-and-restore.md](database-reset-and-restore.md)**.

---

## 11. Odkazy v repu

- `deploy/deploy.sh` — jediný produkční vstup „co se na serveru spouští“.
- `deploy/docker-compose.yml` — šablona runtime Compose (kopíruje se do `/opt/ems-deploy`).
- `.gitea/workflows/deploy.yml` — napojení na runner + job kontejner.
- `docs/database-reset-and-restore.md` — zahození dat Postgres/Timescale a import zálohy.


## CI/deploy opravy 2026-06-11/12 (container mód runneru, slabý server)

Tři nezávislé vady, které od 6. 6. blokovaly auto-deploy (runy 358–369):

1. **Secret `EMS_CI_FLYWAY_URL`** mířil na `localhost` — DB poslouchá na
   `EMS_DB_BIND` (10.200.200.1). Validate flyway běží s `--network host`.
2. **Bind mounty v container módu**: docker CLI v jobu mluví s HOSTOVSKÝM
   daemonem → `-v` cesty checkoutu neexistují → flyway dostal prázdné adresáře
   („applied migration not resolved locally"). Fix: `docker create` +
   `docker cp` do **`/sql`** (ne `/flyway/sql` — image tam má VOLUME, který by
   kopii zastínil) — `scripts/ci_flyway_validate_remote.sh`.
3. **Pending repeatables**: flyway 12 validate selže na nové/změněné R__ —
   ignorovat `*:pending` (CI skript i `deploy/deploy.sh`; immutabilitu
   verzovaných hlídá `ci_check_migration_immutability.sh`).

Dále: workflow deploy step si **sám instaluje čerstvý `deploy.sh`** z checkoutu
(opravy skriptu se propagují bez ručního zásahu) a `deploy.sh` **stopne
backend/frontend/postgrest PŘED flyway** — slabý server se s běžícím stackem
+ buildem dusil tak, že flyway nedostal spojení k DB (run 369: 9,5 min → EOF).
Výpadek app vrstvy během deploye = navržená degradace (Loxone fallback,
TeltoCharge failsafe).
