Deploying Astro Projects with Dokploy and Nixpacks with Cache Optimization for Faster Builds

1. Dokploy Configuration

Dokploy is an open-source, self-hosted deployment platform. It is designed as a free alternative to Heroku, Vercel, and Netlify, built on Docker and Traefik.

1. Create a new project and connect your GitHub repository

2. Set environment variables

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. Disable cache cleaning

Project Service → Clean Cache: Disabled
Web Server → Daily Docker Cleanup: Disabled

2. Nixpacks Build Engine

Nixpacks, developed by Railway, is an open-source tool that builds source code into standard Docker images. Dokploy uses Nixpacks as its default build engine and supports configurations in a nixpacks.toml or nixpacks.json file.

Create a nixpacks.toml file in the root directory of your project with cache directories specified.

Configuration priority (low → high):

Provider default logic
nixpacks.toml
Environment variables
CLI arguments

Common environment variables

Variable	Description
`NIXPACKS_INSTALL_CMD`	Custom install command
`NIXPACKS_BUILD_CMD`	Custom build command
`NIXPACKS_START_CMD`	Custom start command
`NIXPACKS_PKGS`	Additional Nix packages to install
`NIXPACKS_APT_PKGS`	Additional Apt packages to install
`NIXPACKS_INSTALL_CACHE_DIRS`	Cache directories during install
`NIXPACKS_BUILD_CACHE_DIRS`	Cache directories during build
`NIXPACKS_NO_CACHE`	Disable cache (not recommended)
`NIXPACKS_CONFIG_FILE`	Specify config file
`NIXPACKS_DEBIAN`	Use Debian base image

3. Astro Project Configuration

Astro is a modern web framework ideal for content-rich sites like blogs, marketing pages, and e-commerce. Large amounts of static assets can slow down builds—but with cache, you can significantly speed them up.

1. Specify the directory for build cache outputs

Set the cache directory in Astro’s config file. This path may be absolute or relative and is used in subsequent builds.

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

2. Nixpacks Cache Config File

Create a nixpacks.toml file in the root of your Astro project with cache directories and build commands.

# Use specific Node.js and pnpm versions
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# Install dependencies with pnpm cache
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# Build Astro project and cache node_modules/.cache and astro_cache
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# Start command (placeholder, assuming NGINX serves `dist`)
[start]
cmd = "echo 'Build complete. Please serve the dist directory with NGINX.'"

4. Optimize Docker Build Context

Add a .dockerignore file in your Astro project root:

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

5. Deployment & Validation

After deploying on Dokploy, verify that the build log shows the following to confirm that caching is active:

1. Build command mounts cache directories

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. Astro reused cached entries (e.g., for image optimization)

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

✅ If you see --mount=type=cache and reused cache entry, caching is working properly and build time is reduced.

🎉 From Dokploy’s Deployments tab, you can see the build time drop from 31 minutes to just 3 minutes with caching—saving both time and bandwidth.

6. Notes

Keep Astro cacheDir and Nixpacks cacheDirectories consistent
Each build phase must explicitly define cache directories
nixpacks.toml supports "..." to merge with env variables
By default, node_modules/.astro is not cached—explicitly assign to astro_cache