Sites estáticos

O site estático é um recurso do canvas do ambiente. Ele faz o build de um repositório (ou recebe uma pasta pronta) e publica os arquivos num servidor compartilhado da plataforma: não há um pod por site, então o custo é por armazenamento e transferência, não por instância.

Use para documentação, landing pages, blogs e aplicações de página única (SPA). Quando a aplicação precisa de renderização no servidor (SSR, ISR ou rotas de API), use uma aplicação.

Criar um site

1. No canvas do ambiente, adicione um recurso Site estático.
2. Informe o repositório e a branch (o repositório precisa estar ligado à organização, como numa aplicação).
3. Escolha o preset ou deixe em auto:

Preset	Detecção	Build	Saída
vite	dependência vite	<gerenciador> run build	dist
nextjs-export	dependência next	<gerenciador> run build	out (exige output: 'export')
astro	dependência astro	<gerenciador> run build	dist
docusaurus	dependência @docusaurus/core	<gerenciador> run build	build
hugo	hugo.toml, hugo.yaml ou config.toml com baseURL	hugo --minify --baseURL $ATLAS_SITE_URL	public
none	—	nenhum	o diretório configurado

O gerenciador de pacotes vem do lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock ou bun.lockb). Sem lockfile o build falha com static_build.lockfile_missing: builds reprodutíveis exigem um.

4. Aplique a revisão. O site é criado e o primeiro build começa. O endereço padrão (<nome>-<sufixo>.apps.<domínio>) aparece nas saídas PUBLIC_URL e HOST do nó, que outros nós podem referenciar.

Variáveis de build

As variáveis de build (CHAVE=valor) vão para o bundle publicado, que é público. Por isso só valores não secretos são aceitos: uma referência a um segredo ou a uma saída secreta (${{ banco.DATABASE_URL }}) é recusada no campo com static_site.secret_in_build. Referências a saídas comuns (${{ api.PUBLIC_URL }}) são resolvidas no build; quando o valor muda, o site aparece com rebuild pendente.

A plataforma ainda injeta ATLAS_SITE_URL, ATLAS_COMMIT_SHA e NODE_ENV=production.

Deploys e rollback

Cada build gera um deploy imutável. Na aba Deploys do nó você vê o estado (na fila, construindo, empacotando, pronto, ativo, falhou, bloqueado ou expirado), o commit, o tamanho e o autor.

• Com Ativar automaticamente (padrão), o deploy pronto passa a ser servido na hora.
• Ativar um deploy anterior é o rollback: nenhum build novo roda e o site muda em segundos.
• Os deploys mais antigos que a retenção do plano (sites.retainedDeploys) expiram; o deploy ativo nunca expira.

Varredura do que é publicado

Antes de publicar, a plataforma procura segredos nos arquivos de saída (chaves de nuvem, tokens de Git, chaves privadas). Encontrando um, o deploy fica bloqueado, o valor aparece mascarado e o deploy ativo não muda.

_redirects e _headers

Os arquivos _redirects e _headers na raiz da saída seguem o formato do Netlify e do Cloudflare Pages:

# _redirects: origem destino [status][!]
/blog/:slug   /posts/:slug   301
/docs/*       /v2/:splat     302
/app/*        /index.html    200

• Status aceitos: 200 (reescrita interna), 301, 302, 307, 308 e 404. ! força a regra mesmo quando o arquivo existe.
• Destino externo (https://...) só com redirecionamento (3xx): reescrita para outro host é recusada (external_rewrite_not_allowed) e o deploy falha com o arquivo e a linha.

# _headers: um padrão por bloco, cabeçalhos indentados
/assets/*
  Cache-Control: public, max-age=31536000, immutable
/*
  X-Frame-Options: DENY

Set-Cookie, Content-Length, Content-Encoding, Vary, ETag, Host e qualquer x-atlas-* não podem ser definidos (header_not_allowed).

SPA e página 404

Com SPA ligado, qualquer rota sem arquivo e sem extensão devolve o index.html. A página 404 (padrão 404.html) é servida com status 404 quando nada mais casa.

Cache e CDN

Sem CDN, os sites passam por um cache na borda da plataforma: arquivos com hash no nome (assets/app-3f9a8c7d.js) ficam em cache por um ano; o HTML é revalidado em poucos segundos. Por isso um rollback aparece em até 20 segundos.

Nos planos com cdn.enabled, Admin ou Owner do projeto liga a CDN do site na aba Domínios e CDN. A plataforma registra o site no provedor configurado pelo administrador, mostra o destino CNAME e limpa o cache da CDN a cada ativação.

Transferência e armazenamento

A transferência entregue (pela borda ou pela CDN) conta na franquia mensal sites.transferGbMonthly. A aba Uso mostra o mês, o percentual e o armazenamento. A 80% aparece um aviso. Acima da franquia:

• com sites.transferOverage = BLOCK (Starter), o site responde 429 até a virada do mês ou uma troca de plano;
• com ALLOW, o excedente é cobrado.

Upload de pasta pronta (CLI)

coda sites deploy ./dist --site docs      # empacota, envia e publica
coda sites deploys docs                   # lista os deploys
coda sites rollback docs                  # ativa o deploy pronto anterior

Limites por plano

Chave	Starter	Pro	Business	Enterprise
sites.maxSites	3	20	100	500
sites.maxDeploySizeMiB	100	500	1.024	2.048
sites.maxFiles	5.000	20.000	50.000	100.000
sites.retainedDeploys	5	20	50	100
sites.transferGbMonthly	10	100	1.000	5.000
sites.transferOverage	BLOCK	ALLOW	ALLOW	ALLOW
cdn.enabled	não	sim	sim	sim

Cada arquivo tem no máximo 25 MiB.