Instalação
Docker Compose
Host único, sem Kubernetes. O caminho mais rápido até uma stack rodando, e o que o CI usa
como smoke test. Dois formatos: um loop de desenvolvimento sem credenciais (make up) e uma
instalação com formato de produção (make up-prod). Esta página cobre os dois; as posturas
de autenticação deles diferem de propósito (veja "Autenticação: dois formatos" abaixo).
Pré-requisitos
| Requisito | Versão | Por quê |
|---|---|---|
| Docker Engine | 24 ou mais novo (validado com 29.1.3) | Os arquivos do compose usam read_only, entradas tmpfs com size/mode/uid/gid e deploy.resources por serviço fora do modo Swarm: tudo recurso da Compose Spec, não a sintaxe antiga de docker-compose.yml v2/v3. |
| Docker Compose | v2, o plugin docker compose (validado com a v2.40.3), não o docker-compose v1 autônomo em Python | A chave name: de nível superior e os recursos acima exigem a Compose Spec, que a v1 não implementa. |
openssl | qualquer versão recente | Gerar os tokens de autenticação; veja abaixo. |
| ~1 GiB de RAM livre | n/a | Os limites de recurso da base (up-prod) somam ~1 GiB (web 512 MiB + orbit-api 256 MiB + nocturne 256 MiB). O override de desenvolvimento (up) eleva os limites para ~2 GiB somados, para dar folga a um build local. Isso é um teto, não um requisito; o uso em repouso é bem menor. |
Confirme o que você tem:
docker --versiondocker compose versionTodas as portas
| Variável | Default | Para que serve |
|---|---|---|
WEB_HOST_PORT | 3000 | Porta do host publicada para o web. Mude esta, não a porta do contêiner. |
ORBIT_API_HOST_PORT | 8080 | Porta do host publicada para o orbit-api, para depuração local; o navegador nunca deveria precisar dela diretamente (veja architecture.md). |
NOCTURNE_HOST_PORT | 8081 | Porta do host publicada para o nocturne, com a mesma ressalva de depuração, ainda mais forte: em uma instalação real, o nocturne não pode ser alcançável de fora deste host. |
ORBIT_STACK_HOST_PORT | 8082 | A API do engine de telemetria no loopback, para o remote-write de um agente local ou um curl. |
ORBIT_STACK_METRICS_HOST_PORT | 9092 | O listener de métricas do engine no loopback. |
As portas dos contêineres são fixadas pelo CONTRACT.md e não são configuráveis: web em
3000, orbit-api em 8080 (API) e 9090 (métricas, Adendo v0.2), nocturne em 8081
(API) e 9090 (métricas), orbit-stack em 8082 (API) e 9090 (métricas).
Armazenamento
Todo contêiner roda com sistema de arquivos raiz somente-leitura e um tmpfs em /tmp.
Dois guardam estado em um volume nomeado. O orbit-stack mantém seus blocos, seus
write-ahead logs e seus segmentos de trace no orbit-stack-data, montado em /data. O
orbit-api mantém usuários, papéis, sessões, dashboards salvos e a trilha de auditoria no
orbit-api-data, montado em /var/lib/sreorbit (ORBIT_DATA_DIR). O make down remove os
dois junto com a rede (ele roda docker compose down --volumes), então cada conta, dashboard
e linha de auditoria vai embora com eles; para mantê-los entre destruições, pare a stack com
docker compose stop ou faça backup dos volumes antes (os comandos estão no
../operations.md). Dimensione o volume do engine para os dias de
ORBIT_STACK_RETENTION multiplicados pelos bytes por amostra da sua carga de trabalho (a
página de benchmark dá 1,7 B por amostra em uma carga com formato de scrape), mais uma
duração de bloco de write-ahead log.
Autenticação: dois formatos, e por que eles diferem
O docker-compose.override.yml existe por um motivo, declarado no próprio cabeçalho dele:
"the stack runs with zero credentials" (a stack roda com zero credenciais). O loop
de desenvolvimento completo do adendo (make up, base + override) roda os dois serviços de backend com
ORBIT_AUTH_MODE=disabled / NOCTURNE_AUTH_MODE=disabled: nenhum token a gerar, nenhum
token a vazar de um laptop. O make up-prod (apenas o arquivo base, publicando imagens em
vez de construí-las) roda no modo static, casando com o default do próprio CONTRACT.md, e
exige tokens reais, ou os serviços de backend se recusam a iniciar.
Gere-os uma vez, independentemente do formato que você estiver usando (você vai precisar
deles no instante em que trocar para o up-prod):
openssl rand -hex 32 # → ORBIT_AUTH_TOKENopenssl rand -hex 32 # → NOCTURNE_AUTH_TOKENSe o seu docker-compose.yml for anterior ao Adendo v0.2
services/ e deploy/ estão em desenvolvimento ativo enquanto esta página é escrita; o
status.md lista o que já chegou. Se os passos abaixo não
surtirem efeito (os contêineres sobem, mas as variáveis não ficam visíveis dentro deles), os
seus arquivos do compose ainda não repassam essas variáveis, e você precisa acrescentá-las.
O Compose só repassa variáveis que o bloco environment: de um serviço referencie
explicitamente; defini-las apenas no .env não basta. Acrescente:
Em deploy/compose/docker-compose.yml, web.environment:
ORBIT_API_URL: ${ORBIT_API_URL:-http://orbit-api:8080}
ORBIT_AUTH_TOKEN: ${ORBIT_AUTH_TOKEN:-}Em deploy/compose/docker-compose.yml, orbit-api.environment:
ORBIT_AUTH_MODE: ${ORBIT_AUTH_MODE:-static}
ORBIT_AUTH_TOKEN: ${ORBIT_AUTH_TOKEN:-}
ORBIT_OIDC_ISSUER: ${ORBIT_OIDC_ISSUER:-}
ORBIT_OIDC_AUDIENCE: ${ORBIT_OIDC_AUDIENCE:-}
ORBIT_METRICS_ADDR: ${ORBIT_METRICS_ADDR:-:9090}
NOCTURNE_AUTH_TOKEN: ${NOCTURNE_AUTH_TOKEN:-}Em deploy/compose/docker-compose.yml, nocturne.environment:
NOCTURNE_AUTH_MODE: ${NOCTURNE_AUTH_MODE:-static}
NOCTURNE_AUTH_TOKEN: ${NOCTURNE_AUTH_TOKEN:-}
NOCTURNE_OIDC_ISSUER: ${NOCTURNE_OIDC_ISSUER:-}
NOCTURNE_OIDC_AUDIENCE: ${NOCTURNE_OIDC_AUDIENCE:-}
NOCTURNE_METRICS_ADDR: ${NOCTURNE_METRICS_ADDR:-:9090}E em deploy/compose/docker-compose.override.yml, para que o loop de desenvolvimento sem
credenciais continue sem credenciais:
orbit-api:
environment:
ORBIT_AUTH_MODE: disabled
nocturne:
environment:
NOCTURNE_AUTH_MODE: disabled(Nenhum dos arquivos do compose passa mais NEXT_PUBLIC_API_URL: o apps/web/Dockerfile
não a consome, e uma cópia antiga no seu próprio override seria um no-op sobre o qual o
Docker emite aviso. Apague-a se você trouxe uma.)
Instale
O repositório não é público, e nada nesta página o baixa. Rode todos os comandos abaixo a
partir da raiz da árvore de código-fonte do SRE Orbit que você recebeu, o diretório que
contém o Makefile, o .env.example e o deploy/. O make up-prod só precisa do
deploy/compose/ e do .env dessa árvore, e baixa as imagens publicadas; o make up as
constrói a partir da árvore.
cp .env.example .envAcrescente os dois tokens que você gerou acima (necessários para o up-prod; inofensivos
mesmo se você só for rodar o up, já que o override de desenvolvimento força o modo
disabled de qualquer jeito):
cat >> .env <<'EOF' # --- Addendum v0.2 ----------------------------------------------------------ORBIT_AUTH_MODE=staticORBIT_AUTH_TOKEN=REPLACE_WITH_YOUR_FIRST_GENERATED_TOKENORBIT_METRICS_ADDR=:9090NOCTURNE_AUTH_MODE=staticNOCTURNE_AUTH_TOKEN=REPLACE_WITH_YOUR_SECOND_GENERATED_TOKENNOCTURNE_METRICS_ADDR=:9090EOFSubstitua os dois placeholders REPLACE_WITH_... pelas duas saídas de
openssl rand -hex 32 geradas acima antes de continuar, com sed -i ou com o seu editor. Não deixe o
texto literal do placeholder no .env.
Depois suba a stack. Loop de desenvolvimento (build a partir do código, zero credenciais, dados de demonstração):
make upEquivalente sem make:
docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml \ -f deploy/compose/docker-compose.override.yml \ up -d --build --remove-orphansCom formato de produção (imagens publicadas, autenticação static, exige que os tokens
acima sejam reais):
make up-prodEquivalente sem make:
docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml \ up -d --remove-orphansComo é uma instalação saudável
docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml psOs cinco serviços aparecem como Up com saúde (healthy): o healthcheck do web começa a
passar dentro do start_period de 20s; os serviços de backend, em até 10s. O quinto é o
orbit-shop, a loja de demonstração: oito pequenos serviços em um único processo que enviam
traces para o engine, para que as páginas de APM tenham algo a mostrar
(../apm.md → "A loja de demonstração"). O ORBIT_SHOP_RPS no .env define a
carga dela (padrão de 5 requisições por segundo), e
docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml stop orbit-shop
a desliga. Se algum serviço aparecer como (unhealthy) ou ficar reiniciando, vá direto para
troubleshooting.md.
Faça login
O console pede um usuário. O Compose roda o orbit-api com dados de demonstração
(ORBIT_DEMO_DATA=true), então, na primeira inicialização, com o volume vazio, ele cria três
contas, admin, editor e viewer, que usam a senha de ORBIT_DEMO_PASSWORD, ou uma
aleatória quando o .env a deixa vazia, impressa uma vez em docker compose logs orbit-api (o
campo demo_password). A página de login as lista: escolha uma para ver o que aquele papel
enxerga. Para começar com um administrador
seu, acrescente o par ao .env antes do primeiro up
(../identity.md → "O primeiro administrador" gera o verificador):
echo "ORBIT_ADMIN_USER=admin" >> .envecho "ORBIT_ADMIN_PASSWORD_VERIFIER=$(node apps/web/scripts/hash-password.mjs < admin-password)" >> .envO admin-password é um arquivo com a senha do administrador, de 15 caracteres ou mais. O
par só vale enquanto o volume não tiver nenhum usuário; para recomeçar do zero, rode
make down (que apaga o volume) e up de novo.
Verifique
curl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/healthzcurl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/readyzTodas as outras rotas exigem uma sessão e, com a autenticação static (make up-prod),
também o bearer. Com a autenticação desligada (o loop de desenvolvimento do make up),
o bearer é ignorado, então os mesmos comandos funcionam nos dois casos; defina TOKEN com o
valor de ORBIT_AUTH_TOKEN do seu .env:
TOKEN=REPLACE_WITH_YOUR_ORBIT_AUTH_TOKENDEMO_PASSWORD="$(docker compose logs orbit-api | grep -o '"demo_password":"[^"]*"' | cut -d'"' -f4)"curl -fsS -H "Authorization: Bearer $TOKEN" http://localhost:${ORBIT_API_HOST_PORT:-8080}/api/v1/auth/stateSESSION="$(curl -fsS -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d "{\"username\":\"admin\",\"password\":\"$DEMO_PASSWORD\"}" http://localhost:${ORBIT_API_HOST_PORT:-8080}/api/v1/auth/login \ | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')"curl -fsS -H "Authorization: Bearer $TOKEN" -H "X-Orbit-Session: $SESSION" \ http://localhost:${ORBIT_API_HOST_PORT:-8080}/api/v1/version(DEMO_PASSWORD é a senha das contas de demonstração, tirada do log da primeira
inicialização; com um administrador seu, use a senha dele.) Depois abra http://localhost:${WEB_HOST_PORT:-3000}/ no navegador: o site
institucional renderiza, e o /deck pede login e então mostra o parque de demonstração.
Atualize
Troque a árvore de código-fonte pela nova versão que você recebeu, mantenha o seu .env e
faça o build de novo:
docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml \ up -d --build --remove-orphansOs volumes nomeados sobrevivem a uma atualização: usuários, dashboards, a trilha de auditoria e a telemetria continuam lá.
Para o up-prod, primeiro atualize o IMAGE_TAG no .env para a nova versão publicada e
então rode o comando do up-prod de novo; o compose baixa a nova tag e recria os
contêineres cuja imagem ou configuração mudou, deixando os outros intactos.
Faça rollback
O Compose não tem histórico de releases embutido. Diferentemente do Helm, "rollback" aqui significa "reinstale você mesmo a versão anterior", então você precisa saber qual era essa versão:
# IMAGE_TAG in .env: set it back to the last known-good value, then:docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml up -d --remove-orphansSe você construiu localmente em vez de baixar imagens publicadas, isso só funciona se a
imagem antiga ainda estiver no seu cache local do Docker
(docker image ls | grep sreorbit); caso contrário, o compose não tem para onde voltar.
O travamento por digest do install/helm.md fecha essa lacuna; se o rollback byte a byte
importa para você, use esse caminho em vez do compose.
Desinstale de forma limpa
make down# equivalent:docker compose --project-name sreorbit --env-file .env \ -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml \ down --volumes --remove-orphansIsso remove os contêineres, a rede sreorbit e os dois volumes nomeados, orbit-stack-data
(telemetria e traces) e orbit-api-data (usuários, dashboards e a trilha de auditoria): faça
backup deles antes se quiser mantê-los. Não remove o
.env (ele guarda os seus tokens gerados; apague-o você mesmo quando terminar: rm .env)
nem qualquer imagem que você tenha baixado ou construído
(docker image rm ghcr.io/sreorbit/{web,orbit-api,nocturne,orbit-stack}:$IMAGE_TAG, ou make clean para
os builds locais com tag de desenvolvimento).
Para onde ir em seguida
- Cada variável usada acima, com o significado completo:
../configuration.md. - O que cada healthcheck verifica, e a armadilha de fazer probe de
/healthznoweb:../troubleshooting.md. - Migrando para um cluster real:
helm.md.