Conceitos

Visão geral

flowchart LR
  T[Time] --> K[Token nbk_]
  T --> PR[Projeto = grupo]
  PR --> SV[Serviço app]
  PR --> DB[Serviço database]
  PR --> SH[Variáveis shared]
  SV --> VAR[Variáveis]
  SV --> VOL[Volume]
  SV --> DOM[Domínio]
  SV --> DEP[Deploy]
  T --> G[Galeria]
  G --> A[Arquivo]

Time e token

• Time: dono dos recursos e dos tokens. Um token pertence ao time, nunca a uma pessoa.
• Token de API (nbk_…): credencial com escopos e, opcionalmente, restrita a alguns projetos (project_ids) ou galerias. Veja Token de API e Tokens e escopos.

Projeto (grupo)

Um projeto é um grupo de serviços. Todos os serviços do projeto ficam numa rede privada própria (nunca alcançam outro projeto) e têm em comum as variáveis shared do projeto, que cada serviço usa referenciando-as com ${{shared.NOME}} (não entram sozinhas). Veja Rede privada.

Serviço

Um serviço pertence a um projeto. Campos principais:

Campo	Significado
name	^[a-z][a-z0-9-]{0,30}$, único no projeto; é o hostname na rede privada. Imutável.
kind	app (seu código ou imagem) ou database (criado pela rota de bancos). Imutável.
visibility	public (recebe slug e URL pública) ou private (só na rede do projeto, sem rota pública). Se omitida, o padrão é private: informe public e um slug para ter URL.
source	{"type":"upload"}, {"type":"git","installation_id","repo","branch","root_dir","watch_paths"} ou {"type":"image","ref"}, com ref = repo[:tag]@sha256:<digest> para fixar a versão (Imagem pública).
build	{"builder":"auto|node|go|rust|python|static|dockerfile","dockerfile_path":"Dockerfile"}.
port	porta interna (padrão 3000).
healthcheck_path, start_command, build_command	opcionais.
resources (memory_mb, cpus)	recursos (padrão 512 MB e 0.5 CPU; máximo por plano). Veja Escala e recursos.
auto_deploy	deploy automático por git.

Todo serviço roda como não-root, com sistema de arquivos somente leitura (só /tmp e o volume são graváveis). Veja Isolamento.

O serviço web padrão

Todo projeto novo nasce com um serviço web (kind=app, fonte upload, build.builder=auto, porta 3000). Ele nasce public, já com slug e public_url gerados (por exemplo web-br5pg0 e https://web-br5pg0.<dominio-de-apps>), mesmo que o padrão de visibility ao criar outros serviços seja private. Use PATCH .../services/web para adaptá-lo (fonte, build, porta) em vez de criar outro; um POST com name: "web" dá 409 name_taken.

Para torná-lo privado: PATCH .../services/web com {"visibility": "private"}. O slug e a public_url desaparecem e ele passa a ser alcançável só na rede do projeto. Voltando a public sem informar slug, a plataforma deriva um do nome.

P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\": \"web-padrao-$(date +%s)-$RANDOM\"}" | jq -r .id)
# o web padrão nasce público, com slug e public_url
curl -sS "$NEBULAR_API/v1/projects/$P/services" -H "Authorization: Bearer $NEBULAR_TOKEN" \
  | jq -e '.items[] | select(.name == "web") | .visibility == "public" and (.slug | length) > 0 and (.public_url | length) > 0' >/dev/null
# tornar privado
curl -sS -X PATCH "$NEBULAR_API/v1/projects/$P/services/web" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"visibility": "private"}'

Variáveis e referências

Variável: escopo service (só aquele serviço) ou shared (guardada no projeto; só chega ao serviço que a referencia com ${{shared.NOME}}). O valor pode referenciar outro serviço com ${{servico.VAR}} ou o grupo com ${{shared.VAR}}; a resolução acontece no deploy. Veja Variáveis e referências.

Volume

Disco persistente de um serviço (1 a 50 GB, 1 por serviço), montado em um caminho absoluto; sobrevive a redeploy. Veja Volumes.

Banco

Serviço kind=database com motor postgres, mariadb ou sqlite, num nó de banco gerenciado. Entrega variáveis prontas (DATABASE_URL etc.) para referenciar. Veja PostgreSQL, MariaDB, SQLite.

Domínio

Todo serviço público tem um subdomínio gerado; você pode anexar domínio próprio. Veja Subdomínio gerado e Domínio próprio.

Deploy

Um deploy constrói e sobe uma versão de um serviço (ou do grupo inteiro, em ordem topológica das referências). Estados: queued, building, deploying, ready, failed, blocked, canceled, superseded. O agent acompanha por polling com backoff. Veja Deploys e status.

Galeria e arquivo (CDN)

• Galeria: pasta de arquivos do time servida pela CDN, com key pública e imutável.
• Arquivo (asset): um nome dentro de uma galeria; enviar o mesmo nome cria uma versão.
• URL imutável e URL alias: veja Visão geral da CDN.
• Varredura: todo arquivo é varrido antes de publicar: Classes de arquivo e varredura.