Lokální vývoj

Lokální vývoj

Sencai je event-driven microservices architektura spravovaná přes Docker Compose. Tento průvodce vás naučí, jak stack spustit lokálně.

Požadavky

• Docker ≥ 20.10
• Docker Compose ≥ 2.0
• Git
• Node.js ≥ 18 (pro lokální vývoj jednotlivých služeb)
• Minimálně 8 GB RAM (doporučeno 12 GB)
• Minimálně 20 GB volného místa

Naklonování repozitáře

git clone https://github.com/sencai-ai/sencai.space.git
cd code

Nastavení prostředí

1. Zkopírujte šablonu:

cd orchestration
cp .env.example .env

2. Vyplňte kritické proměnné:

JWT_SECRET=$(openssl rand -base64 32)
API_MANAGER_ENCRYPTION_KEY=$(openssl rand -base64 32)
APP_KEYS=$(openssl rand -hex 16),$(openssl rand -hex 16),$(openssl rand -hex 16),$(openssl rand -hex 16)
ADMIN_ENCRYPTION_KEY=$(openssl rand -hex 32)

3. Upravte .env a doplňte zbývající hodnoty (cloud tokeny, SMTP atd.)

Spuštění stacku

Základní příkaz:

cd orchestration
./run-local.sh [profily...]

Profily

run-local.sh bez argumentů spustí výchozí sadu profilů (orchestration/run-local.sh, proměnná DEFAULT_PROFILES):

core,traefik,backend,backend-db,auth,git,mq,webhook,monitoring,frontend,web,cloud,docs,admin,audit,agent,vault,billing,watchdog,glitchtip,posthog,opsloop,llm,backup,cell,bootstrap

Profil	Služby
core	API Manager + ssh-proxy-service + workspace-connector (+ Traefik)
backend / backend-db	Strapi backend / jeho MySQL
frontend	Nuxt platform frontend (auth + gravity)
web	Veřejný marketingový web (sencai-web, nginx SSG)
admin	Admin dashboard (sencai-admin)
audit	Sencai Audit viewer (port 3300, audit.sencai.localhost)
auth	Keycloak + keycloak-db + auth-service-consumer
mq	RabbitMQ (sencai-mq) + notification-service + event-store-consumer
webhook	Webhook Publisher
cloud	Cloud Connector + worker + PostgreSQL
git	Gitea Apps + MySQL + act-runner + Git Connector
docs	Dokumentace (Astro 5 + Starlight — tento web)
agent	agent-gateway (fleet C2 brána, port 4400)
billing	billing-adapter (Lago/Stripe, port 3600)
watchdog	sencai-watchdog (dunning microservice — payment-failure suspend/archive cron, port 3700)
llm	llm-service (LLM fasáda, port 4430)
opsloop	opsloop-consumer (intelligence loop, port 3005)
backup	backup-scheduler (MySQL → S3/GCS)
cell	cell-metadata (region/cell routing)
vault	HashiCorp Vault
monitoring	Prometheus, Grafana, Loki, Tempo, OTEL collector, exportéry, Alertmanager, uptime-kuma
bootstrap	One-shot seed dat do Strapi
forum	Sencai Forum (Lemmy backend + UI + Postgres + pict-rs + oauth2-proxy) — není ve výchozí sadě, spouští se explicitně
all	Vše najednou

Příklady

# Pouze backend + auth
./run-local.sh core backend auth mq

# Vše
./run-local.sh all

Lokální adresy

Po spuštění přistupujte ke službám přes Traefik na jejich *.sencai.localhost hostnamech — to je primární způsob přístupu k celému stacku (přímý přístup přes port je záložní debug varianta, viz níže):

Služba	URL	Poznámka
App / Frontend	http://app.sencai.localhost/	Nuxt platform (auth + gravity dashboard)
Backend API	http://app.sencai.localhost/api	Strapi
Strapi Admin	http://app.sencai.localhost/admin	Při prvním přihlášení vytvořte admin účet
Keycloak	http://app.sencai.localhost/kc	viz poznámka níže — holé PathPrefix, bez Host()
Cloud Console	http://app.sencai.localhost/cloud	Cloud Connector — holé PathPrefix, bez Host()
Gitea Apps	http://app.sencai.localhost/gitea-apps	holé PathPrefix, bez Host()
Dozzle (kontejnerové logy)	http://app.sencai.localhost/dozzle	holé PathPrefix, bez Host()
Admin Dashboard	http://admin.sencai.localhost/	sencai-admin
Audit Viewer	http://audit.sencai.localhost/	port 3300
Marketingový web	http://sencai.localhost/	sencai-web
Dokumentace (tento web)	http://docs.sencai.localhost/
GraphQL Gateway	http://graphql.sencai.localhost/
RabbitMQ UI	http://mq.sencai.localhost/	admin / admin
Grafana	http://grafana.sencai.localhost/	admin / admin
Prometheus	http://prometheus.sencai.localhost/
Alertmanager	http://alertmanager.sencai.localhost/
Status / Uptime Kuma	http://status.sencai.localhost/	při prvním spuštění vytvořte admin účet
Traefik Dashboard	http://localhost:8080	není za Traefikem samotným
Lago Billing	http://lago.sencai.localhost/	profil: billing
Vault	http://vault.sencai.localhost/	profil: vault
GlitchTip	http://glitchtip.sencai.localhost/	profil: glitchtip, při prvním spuštění vytvořte admin účet
PostHog	http://posthog.sencai.localhost/	profil: posthog, při prvním spuštění vytvořte admin účet
Agent Gateway (Fleet C2)	http://agent-gateway.sencai.localhost/	profil: agent
Opsloop Consumer	http://opsloop.sencai.localhost/	profil: opsloop
LLM Service	http://llm.sencai.localhost/	profil: llm
Notification Service	http://notify.sencai.localhost/	profil: mq
Workspace Connector	http://workspace-connector.sencai.localhost/	profil: core
SSH Proxy (terminál v prohlížeči)	http://ssh-proxy.sencai.localhost/	profil: core
Cell Metadata	http://cell.sencai.localhost/	profil: cell
Sencai Forum	http://forum.sencai.space/ nebo http://forum.localhost/	profil: forum

Doplnění do /etc/hosts

127.0.0.1 app.sencai.localhost admin.sencai.localhost audit.sencai.localhost sencai.localhost docs.sencai.localhost graphql.sencai.localhost mq.sencai.localhost grafana.sencai.localhost prometheus.sencai.localhost alertmanager.sencai.localhost status.sencai.localhost lago.sencai.localhost vault.sencai.localhost glitchtip.sencai.localhost posthog.sencai.localhost agent-gateway.sencai.localhost notify.sencai.localhost opsloop.sencai.localhost llm.sencai.localhost workspace-connector.sencai.localhost ssh-proxy.sencai.localhost cell.sencai.localhost forum.localhost

Routy bez Host(): keycloak (/kc), cloud-connector (/cloud), gitea-apps (/gitea-apps) a dozzle (/dozzle) jsou v Traefiku zaregistrované jako holá pravidla PathPrefix(...) bez omezení Host(). Odpovídají tedy za jakýmkoliv hostnamem, který Traefik přijme na web entrypointu — nejen za app.sencai.localhost — takže i http://sencai.localhost/kc nebo http://docs.sencai.localhost/dozzle se doroutuje na tyto služby. Nespoléhejte na hostname jako izolační mechanismus.

Port 80 už je obsazený: na strojích, kde je port 80 obsazený (např. lokální k3s cluster se svým ServiceLB/klipper-lb), nastavte TRAEFIK_WEB_HOST_PORT v .env (např. 8088) a připojte :PORT ke každé URL výše (http://app.sencai.localhost:8088/, http://grafana.sencai.localhost:8088/, …). Traefik Dashboard na portu 8080 tím není dotčen.

Obejití Traefiku (debug přes přímý port)

Každou službu, která má ports: mapování v docker-compose.ports.yml, lze dosáhnout i přímo na jejím kontejnerovém portu, mimo Traefik host-routing — užitečné při zjišťování, jestli problém je v aplikaci, nebo v reverse-proxy vrstvě:

http://localhost:1337/admin   # Strapi admin, přímo
http://localhost:15672        # RabbitMQ UI, přímo

Toto je záložní varianta pouze pro debugging — standardní způsob práce se stackem jsou *.sencai.localhost adresy výše.

Spouštění služeb lokálně

Pro rychlejší vývoj lze služby spouštět mimo Docker:

# Backend (Strapi)
cd sencai.space && npm run develop

# Frontend (Nuxt)
cd sencai.space-frontend && npm run dev

# API Manager
cd api-manager && npm run dev

Databáze

Přístup k MySQL

mysql -h 127.0.0.1 -P 3306 -u root -p

Přístup k PostgreSQL

psql -h localhost -p 5434 -U cloud_user -d cloud_connector

Logy

# Všechny služby
docker compose -f orchestration/docker-compose.yml logs -f

# Jedna služba
docker compose -f orchestration/docker-compose.yml logs -f backend

Úklid

# Zastavit stack
cd orchestration && ./run-local.sh stop

# Smazat úplně vše (včetně dat!)
docker compose -f orchestration/docker-compose.yml down -v

Řešení problémů

Problém	Příčina	Řešení
„Port already in use”	Port je obsazený	Změňte port v .env
Strapi se nespustí	MySQL ještě není ready	Počkejte 30 s a restartujte
RabbitMQ connection refused	Ještě není ready	Zkontrolujte logy
Keycloak 503	Pomalý start (normální)	Počkejte 30–90 s

Kompletní referenci najdete v kořenovém CLAUDE.md.