Runtime de Containers

Quando o Guara Cloud faz o deploy do seu servico, o container roda dentro de um ambiente seguro e protegido. Esta pagina descreve como o runtime funciona e o que voce precisa saber ao escrever seu Dockerfile.

Execucao como non-root

Todos os containers rodam como um usuario non-root com UID 1000 e GID 1000. Isso e aplicado pela plataforma e nao pode ser alterado.

Isso significa:

• O processo da sua aplicacao sempre vai rodar como usuario 1000, independente de qualquer diretiva USER no seu Dockerfile.
• Arquivos dentro da sua imagem devem ser legiveis por todos os usuarios (permissoes 644 para arquivos, 755 para diretorios) — esse e o padrao na maioria das imagens Docker.
• A plataforma remove todas as capabilities Linux, exceto NET_BIND_SERVICE, permitindo que o UID 1000 use uma porta baixa configurada. A porta 8080 continua sendo o padrao recomendado para portabilidade da imagem.

Boas praticas para Dockerfile

Ao escrever um Dockerfile para o Guara Cloud, tenha estas orientacoes em mente:

# Use um usuario non-root na sua imagem para consistencia
FROM node:20-alpine

# Crie um usuario non-root (opcional mas recomendado)
RUN addgroup -g 1000 appgroup && adduser -u 1000 -G appgroup -D appuser

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

# Garanta que os arquivos sejam legiveis por todos (padrao do COPY)
# Evite permissoes restritivas como chmod 700

# Use uma porta nao privilegiada
EXPOSE 8080

# Defina o usuario (Guara Cloud vai sobrescrever para UID 1000 de qualquer forma)
USER appuser

CMD ["node", "server.js"]

Sistema de arquivos

Para as suas aplicacoes, o sistema de arquivos raiz do container e gravavel — mas toda escrita acontece como o usuario non-root (UID 1000). Voce so pode escrever onde o UID 1000 tem permissao, entao caminhos que pertencem ao root (como os diretorios que a imagem nginx padrao traz) ficam inacessiveis, mesmo o sistema de arquivos nao sendo globalmente somente leitura.

Os servicos de catalogo gerenciados pela plataforma (bancos de dados, caches, brokers) rodam com um sistema de arquivos raiz totalmente somente leitura, mais restrito. Esse endurecimento nao se aplica aos containers das suas proprias aplicacoes.

Caminhos graváveis

Para que cargas de trabalho comuns (caches do nginx, arquivos PID, logs, dados temporarios) funcionem de imediato, o Guara Cloud monta os seguintes volumes efemeros graváveis pelo grupo — graváveis pelo UID 1000 independente da posse definida pela imagem base:

Caminho	Finalidade	Limite (todos os perfis)
/tmp	Arquivos temporarios, caches, dados de sessao	256 MiB
/var/run	Arquivos PID, sockets Unix	64 MiB
/var/cache	Caches de aplicacao (nginx, pacotes, etc.)	256 MiB
/var/log	Arquivos de log da aplicacao	128 MiB

Cenarios comuns

Se sua aplicacao tentar escrever em um caminho que pertence ao root fora desses mounts, voce vera um erro Permission denied. Veja solucoes comuns:

Framework/Tool	Caminho padrao de escrita	Solucao
Next.js	.next/cache	Defina NEXT_CACHE_DIR=/tmp/next-cache nas variaveis de ambiente
nginx	/var/cache/nginx	Ja gravavel via /var/cache
PHP	/tmp para sessoes	Ja gravavel
Python/pip	~/.cache/pip	Defina PIP_CACHE_DIR=/tmp/pip-cache
Node.js/npm	~/.npm	Defina npm_config_cache=/tmp/npm-cache
Geral	Especifico da aplicacao	Redirecione escritas para /tmp via variaveis de ambiente

Restricoes de seguranca

O Guara Cloud aplica uma politica de seguranca rigorosa em todos os containers:

Restricao	Descricao
Sem escalacao de privilegios	Containers nao podem obter privilegios adicionais em tempo de execucao
Capabilities minimizadas	Todas sao removidas, exceto NET_BIND_SERVICE; sem acesso a mount ou administracao de rede
Perfil seccomp aplicado	Somente chamadas de sistema seguras sao permitidas (perfil RuntimeDefault)
Sem execucao como root	O processo do container sempre roda como UID 1000
Escritas apenas como non-root	O FS raiz e gravavel, mas somente como UID 1000 — caminhos do root sao somente leitura
Sem token de service account	Containers nao tem acesso a credenciais da API do Kubernetes

Essas restricoes seguem o Kubernetes Pod Security Standards (PSS) perfil restricted, o nivel mais alto de seguranca de containers disponivel.

Configuracao de porta

Sua aplicacao deve ouvir na porta configurada nas configuracoes do servico (padrao: 8080). O Guara Cloud injeta a variavel de ambiente PORT com o valor configurado.

// Exemplo: ler a variavel de ambiente PORT
const port = process.env.PORT || 8080;
app.listen(port);

Resumo

Propriedade	Valor
Usuario de execucao	UID 1000 / GID 1000
Sistema de arquivos	Gravavel, mas somente como UID 1000 (somente leitura para servicos de catalogo)
Caminhos graváveis	/tmp, /var/run, /var/cache, /var/log (mounts graváveis pelo grupo)
Escalacao de privilegios	Desabilitada
Capabilities Linux	Todas removidas, exceto NET_BIND_SERVICE
Perfil seccomp	RuntimeDefault
Porta padrao	8080 (configuravel)