# Conceitos

## Visão geral

```mermaid
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](/comecar/token/) e [Tokens e escopos](/seguranca/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](/conectados/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](/guia/imagem-publica/#fixar-por-digest-e-como-obter-o-digest)). |
| `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](/operacao/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](/seguranca/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.

```bash
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](/conectados/variaveis-e-referencias/).

## 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](/conectados/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](/bancos/postgres/), [MariaDB](/bancos/mariadb/), [SQLite](/bancos/sqlite/).

## Domínio

Todo serviço público tem um subdomínio gerado; você pode anexar domínio próprio. Veja [Subdomínio gerado](/dominios/subdominio-gerado/) e [Domínio próprio](/dominios/dominio-proprio/).

## 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](/operacao/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](/cdn/visao-geral/).
- **Varredura**: todo arquivo é varrido antes de publicar: [Classes de arquivo e varredura](/cdn/classes-de-arquivo-e-varredura/).