Temporal (self-hosted)

Co tato dovednost pokrývá

Provoz self-hosted Temporal stacku běžícího jako služby Docker Compose na jednom VPS: spouštění a zastavování služeb, kontrola zdraví, běh Temporal CLI přes kontejner admin-tools, správa namespaces, běh a inspekce workerů a záludnosti specifické pro nasazení na jednom VPS (chybějící autentizace/firewalling, CORS u UI, perzistence a zálohy Postgresu, migrace schématu při upgradu). Toto je provozní vrstva — pro to, jak psát kód Temporal workflow (determinismus, vzory aktivit, retries, verzování, testování), viz oficiální dokumentaci Temporalu.

Kdy ji použít

• Při zprovoznění nebo provozu self-hosted Temporal stacku na VPS
• Při běhu příkazů Temporal CLI proti serveru (výpis/spuštění/signalizace/ukončení workflow)
• Při vytváření nebo inspekci namespaces, nebo (re)buildu a restartu workerů
• Při řešení problémů nasazení na jednom VPS: expozice bez autentizace, UI bez namespaces, worker s „connection refused“, perzistence databáze nebo nesoulad schématu při upgradu

Nejprve poznejte skutečný stack

Než cokoli spustíte, přečtěte si Compose a env soubory projektu, abyste získali skutečné názvy služeb, porty a databázi — nepředpokládejte. Zkontrolujte docker-compose.yml / compose.yaml (a případné overrides) a .env a identifikujte:

• službu Temporal serveru (image temporalio/auto-setup) a gRPC frontend port (výchozí 7233)
• službu admin-tools (image temporalio/admin-tools) — kde žije temporal CLI
• službu UI (image temporalio/ui) a její port (výchozí 8080)
• službu databáze (Postgres / MySQL / Cassandra) a zda se pro visibility používá Elasticsearch
• službu(y) workerů, pokud jsou v Compose definovány
• používané namespace(s)

Kanonické výchozí hodnoty, pokud hodnota není nalezena (ověřte proti skutečnému souboru): služby temporal, temporal-admin-tools, temporal-ui, postgresql; gRPC 7233; UI 8080. Workery a klienti se dostanou na server přes temporal:7233 uvnitř Compose sítě, nebo 127.0.0.1:7233 na hostu.

Běh stacku

Spouštějte z adresáře s Compose souborem (na VPS, přes SSH):

docker compose up -d                 # start
docker compose ps                    # status
docker compose logs -f temporal      # follow server logs
docker compose restart temporal      # restart one service
docker compose down                  # stop (keeps volumes)

Rychlá kontrola zdraví — frontend je dostupný, pokud toto vrátí výsledek:

docker compose exec temporal-admin-tools temporal operator namespace list

Temporal CLI (přes admin-tools)

Spouštějte CLI příkazy uvnitř kontejneru admin-tools, který je předkonfigurován s TEMPORAL_ADDRESS=temporal:7233:

docker compose exec temporal-admin-tools temporal <command>

Časté operace (každou předchází docker compose exec temporal-admin-tools):

# workflows
temporal workflow list
temporal workflow describe  --workflow-id <id>
temporal workflow show      --workflow-id <id>     # full event history
temporal workflow start     --task-queue <q> --type <Name> --workflow-id <id> --input '<json>'
temporal workflow signal    --workflow-id <id> --name <signal> --input '<json>'
temporal workflow query     --workflow-id <id> --type <query>
temporal workflow terminate --workflow-id <id> --reason "<why>"

# task queues / namespaces
temporal task-queue describe      --task-queue <q>
temporal operator namespace list
temporal operator namespace describe --namespace <ns>

Webové UI (výchozí http://<host>:8080) je snazší cesta k procházení běhů a inspekci historií; CLI je pro skriptování a bezhlavé operace na VPS.

Namespaces

Image auto-setup registruje při prvním startu namespace default. Další vytvořte s retenční dobou:

docker compose exec temporal-admin-tools \
  temporal operator namespace create --retention 7d <namespace>

Retence je hlavní páka nákladů na úložiště — začněte na 7d a zvyšujte ji jen pro namespaces, do kterých se skutečně dotazujete daleko zpět.

Workery

Worker je vlastní Compose služba, buildovaná z app image a nasměrovaná na server:

worker:
  build: { context: ., dockerfile: Dockerfile.worker }
  environment:
    TEMPORAL_HOST: temporal:7233
  depends_on: [temporal]
  restart: unless-stopped

Po změně kódu workflow/aktivit worker znovu buildněte a restartujte:

docker compose up -d --build worker
docker compose logs -f worker

Bezstavové workery škálujte přes docker compose up -d --scale worker=N.

Záludnosti self-hostingu (jeden VPS)

• Bezpečnost — bez autentizace ve výchozím stavu. OSS server nemá žádnou autentizaci; kdokoli dosáhne na 7233, může cokoli. Držte 7233 navázaný na 127.0.0.1 a za firewallem a spouštějte workery na stejném hostu — nebo se na frontend dostávejte přes privátní tunel (např. WireGuard). Pokud musí být UI / gRPC vystaveno, dejte ho za TLS reverse proxy (NGINX).
• UI ukazuje „no namespaces“. Obvykle CORS — nastavte TEMPORAL_CORS_ORIGINS na službě UI na skutečný (HTTPS) hostname.
• „Connection refused“ od workeru. 7233 je záměrně navázaný na localhost — použijte temporal:7233 uvnitř sítě, nebo spusťte worker na hostu.
• Perzistence databáze. DB drží veškerý stav workflow, takže její volume musí být pojmenovaný a perzistentní (např. pgdata:/var/lib/postgresql/data). Zálohujte ji a posílejte mimo host, na cronu:

  docker compose exec -T postgresql pg_dump -U temporal temporal | gzip > temporal-$(date +%F).sql.gz
  

• Upgrady. Verze images auto-setup / admin-tools / ui zvyšujte společně, poté spusťte migraci schématu z admin-tools (temporal-sql-tool ... update-schema). Vynechání způsobí chyby nesouladu schématu.
• Malý VPS / Elasticsearch. ES je náročný na paměť; na malých tarifech buď ES vynechte (pro visibility použijte DB), nebo omezte heap přes ES_JAVA_OPTS=-Xms1g -Xmx1g, abyste předešli OOM killům.