Configuracao de Build

Quando voce deploya a partir de um repositorio GitHub, o Guara Cloud precisa construir uma imagem de container da sua aplicacao. Existem dois metodos de build disponiveis: Dockerfile e Buildpack.

Metodos de build

Dockerfile

Com esse metodo, voce fornece um Dockerfile no seu repositorio. Voce tem controle total sobre o ambiente de build: sistema operacional base, dependencias, comandos de instalacao e configuracao do runtime.

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Buildpack

Com Buildpack, voce nao precisa de um Dockerfile. O Guara Cloud detecta automaticamente a linguagem e o framework da sua aplicacao e constroi a imagem para voce. Buildpacks suportam as linguagens e frameworks mais comuns, como Node.js, Python, Go, Java e Ruby.

Como o metodo e detectado

O Guara Cloud detecta automaticamente qual metodo usar:

Situacao	Metodo usado
Existe um Dockerfile no diretorio raiz	Dockerfile
Nao existe Dockerfile no diretorio raiz	Buildpack

Para monorepos, a deteccao considera o diretorio raiz configurado para o servico. Se voce configurou /apps/api como diretorio raiz, o Guara Cloud procura por apps/api/Dockerfile.

Monorepo

Em repositorios monorepo, o build utiliza apenas o diretorio raiz configurado para o servico. Por exemplo, se o diretorio raiz e /apps/api, o Guara Cloud:

• Procura o Dockerfile em apps/api/Dockerfile
• Define o contexto de build como o diretorio apps/api/
• Ignora arquivos fora desse diretorio para fins de build

Isso garante que cada servico em um monorepo tenha builds independentes e eficientes.

Cache de build

O Guara Cloud utiliza cache de camadas para acelerar builds subsequentes. Quando voce faz um novo deploy, apenas as camadas que mudaram sao reconstruidas. Isso reduz significativamente o tempo de build na maioria dos casos.

Para aproveitar ao maximo o cache com Dockerfile, organize suas instrucoes da mais estavel para a menos estavel:

# Camadas estaveis (mudam raramente)
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Camadas dinamicas (mudam a cada deploy)
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Variaveis de Ambiente no Build

Voce pode marcar variaveis de ambiente como disponiveis durante o build da imagem. Isso permite que valores como tokens de acesso, credenciais de registry e configuracoes de build sejam utilizados no processo de construcao da imagem Docker.

Como funciona

No editor de variaveis de ambiente do dashboard, cada variavel possui um checkbox Build. Ao ativa-lo, a variavel sera passada como um Docker ARG durante o build da imagem. Pela CLI, utilize a flag --build (ou -b) no comando guara env set:

guara env set NPM_TOKEN=seu-token --build

Para que o Dockerfile consuma a variavel, declare-a com a instrucao ARG:

FROM node:20-alpine
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN rm -f .npmrc
EXPOSE 3000
CMD ["node", "server.js"]

Casos de uso comuns

• Tokens npm privados — autenticacao com registries privados durante npm install
• Credenciais de registry de imagens — pull de imagens base privadas
• Configuracoes de build — flags de compilacao, variaveis de feature toggle em tempo de build