Implantando projetos Astro com Dokploy e Nixpacks com otimização de cache para acelerar builds

1. Configuração do Dokploy

Dokploy é uma plataforma de implantação de código aberto e auto-hospedada. Projetada como uma alternativa gratuita ao Heroku, Vercel e Netlify, é baseada em Docker e Traefik.

1. Crie um novo projeto e conecte ao repositório GitHub

2. Configure as variáveis de ambiente

NIXPACKS_NODE_VERSION=22
NIXPACKS_PNPM_STORE_PATH=/root/.local/share/pnpm/store/v3
NIXPACKS_INSTALL_CACHE_DIRS=/app/node_modules
NIXPACKS_BUILD_CACHE_DIRS=/app/node_modules/.cache,/app/astro_cache

3. Desative a limpeza automática de cache

Serviço do projeto → Clean Cache: desativado
Servidor Web → Daily Docker Cleanup: desativado

2. Motor de build Nixpacks

Nixpacks é uma ferramenta de build de código aberto desenvolvida pela Railway que transforma código-fonte em imagens Docker padrão. Dokploy usa Nixpacks como motor de build padrão, com configuração possível via nixpacks.toml ou nixpacks.json.

Crie o arquivo nixpacks.toml no diretório raiz do projeto e defina os diretórios de cache necessários.

Prioridade de configuração (baixa → alta):

Lógica padrão do provider
nixpacks.toml
Variáveis de ambiente
Argumentos CLI

Variáveis de ambiente comuns

Variável	Descrição
`NIXPACKS_INSTALL_CMD`	Comando personalizado de instalação
`NIXPACKS_BUILD_CMD`	Comando personalizado de build
`NIXPACKS_START_CMD`	Comando personalizado de inicialização
`NIXPACKS_PKGS`	Pacotes Nix adicionais
`NIXPACKS_APT_PKGS`	Pacotes Apt adicionais
`NIXPACKS_INSTALL_CACHE_DIRS`	Diretórios de cache durante a instalação
`NIXPACKS_BUILD_CACHE_DIRS`	Diretórios de cache durante o build
`NIXPACKS_NO_CACHE`	Desativa cache (não recomendado)
`NIXPACKS_CONFIG_FILE`	Define arquivo de configuração
`NIXPACKS_DEBIAN`	Usa imagem base Debian

3. Configuração do projeto Astro

Astro é um framework moderno para sites voltados a conteúdo como blogs, páginas de marketing e e-commerce. Quando há muitos recursos estáticos, o tempo de build pode aumentar — mas com cache, você pode otimizá-lo significativamente.

1. Defina o diretório de cache no Astro

Configure o diretório de cache no arquivo astro.config.mjs. Pode ser caminho relativo ou absoluto.

// astro.config.mjs
export default defineConfig({
  cacheDir: './astro_cache',
});

2. Arquivo de configuração de cache do Nixpacks

Crie nixpacks.toml na raiz do projeto Astro, configurando os diretórios de cache e comandos de build.

# Use versões específicas do Node.js e pnpm
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# Instale dependências com cache do pnpm
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Compile o Astro e armazene cache de node_modules/.cache e astro_cache
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# Comando de inicialização (assumindo NGINX servindo dist)
[start]
cmd = "echo 'Build concluído. Sirva o diretório dist via NGINX.'"

4. Otimize o contexto de build Docker

Adicione um arquivo .dockerignore na raiz do projeto Astro:

node_modules
astro_cache
dist
*.log
.DS_Store
.vscode
.env*

5. Implantação e verificação

Após a implantação automática no Dokploy, verifique nos logs se o cache foi utilizado:

1. Comando de build montando diretórios de cache

RUN --mount=type=cache,id=xxxx-node_modules/cache,target=/app/node_modules/.cache \
    --mount=type=cache,id=xxxx-astro_cache,target=/app/astro_cache \
    pnpm run build

2. Reutilização de cache pelo Astro (ex. otimização de imagens)

▶ /_astro/202409272055577_Z2smeTW.avif (reused cache entry)
▶ /_astro/202409272055575_Z2wPyJN.avif (reused cache entry)
▶ /_astro/202409272055577_1IgP6g.avif (reused cache entry)

✅ Se você vir --mount=type=cache e reused cache entry, o cache está funcionando corretamente e o build foi otimizado.

🎉 Na aba Deployments do Dokploy, é possível ver o tempo de build cair de 31 minutos para apenas 3 minutos com cache ativado — economizando tempo e largura de banda.

6. Notas

Mantenha cacheDir (Astro) e cacheDirectories (Nixpacks) consistentes
Declare explicitamente os diretórios de cache em cada fase
nixpacks.toml suporta "..." para mesclar com variáveis de ambiente
Por padrão, node_modules/.astro não é incluído no cache — adicione manualmente em astro_cache