Pular para o conteúdo

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

RequisitoVersãoPor quê
Docker Engine24 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 Composev2, o plugin docker compose (validado com a v2.40.3), não o docker-compose v1 autônomo em PythonA chave name: de nível superior e os recursos acima exigem a Compose Spec, que a v1 não implementa.
opensslqualquer versão recenteGerar os tokens de autenticação; veja abaixo.
~1 GiB de RAM livren/aOs 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:

bash
docker --versiondocker compose version

Todas as portas

VariávelDefaultPara que serve
WEB_HOST_PORT3000Porta do host publicada para o web. Mude esta, não a porta do contêiner.
ORBIT_API_HOST_PORT8080Porta do host publicada para o orbit-api, para depuração local; o navegador nunca deveria precisar dela diretamente (veja architecture.md).
NOCTURNE_HOST_PORT8081Porta 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_PORT8082A API do engine de telemetria no loopback, para o remote-write de um agente local ou um curl.
ORBIT_STACK_METRICS_HOST_PORT9092O 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):

bash
openssl rand -hex 32   # → ORBIT_AUTH_TOKENopenssl rand -hex 32   # → NOCTURNE_AUTH_TOKEN

Se 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:

yaml
      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:

yaml
      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:

yaml
      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:

yaml
  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.

bash
cp .env.example .env

Acrescente 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):

bash
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=:9090EOF

Substitua 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):

bash
make up

Equivalente sem make:

bash
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-orphans

Com formato de produção (imagens publicadas, autenticação static, exige que os tokens acima sejam reais):

bash
make up-prod

Equivalente sem make:

bash
docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml \  up -d --remove-orphans

Como é uma instalação saudável

bash
docker compose --project-name sreorbit --env-file .env \  -f deploy/compose/docker-compose.yml -f deploy/compose/docker-compose.override.yml ps

Os 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):

bash
echo "ORBIT_ADMIN_USER=admin" >> .envecho "ORBIT_ADMIN_PASSWORD_VERIFIER=$(node apps/web/scripts/hash-password.mjs < admin-password)" >> .env

O 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

bash
curl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/healthzcurl -fsS http://localhost:${ORBIT_API_HOST_PORT:-8080}/readyz

Todas 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:

bash
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:

bash
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-orphans

Os 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:

bash
# 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-orphans

Se 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

bash
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-orphans

Isso 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