Dockerize an Astro Static Site: Build dist, Serve It with Caddy

Use a two-stage Dockerfile#

Astro’s deployment guide identifies astro build (or the package-script equivalent) as the build command and dist as the publish directory. Docker multi-stage builds let the final image copy just that artifact instead of carrying the package manager, source files, and node_modules into production.

For a pnpm project, add this Dockerfile at the repository root:

1
FROM node:22-slim AS build
2
WORKDIR /app
3

4
# Copy dependency metadata first so this layer can be cached.
5
COPY package.json pnpm-lock.yaml ./
6
RUN npm install --global [email protected]
7
RUN pnpm install --frozen-lockfile
8

9
COPY . .
10
RUN pnpm build
11

12
FROM caddy:2-alpine
13
COPY --from=build /app/dist /usr/share/caddy
14

15
EXPOSE 80

The order is deliberate. A content or component change does not invalidate the dependency-install layer as long as package.json and pnpm-lock.yaml remain unchanged. The final caddy stage receives only /app/dist; it has no project source or Node package tree to execute.

Use the Node and pnpm versions your repository supports rather than copying these numbers blindly. In this site, the package manifest currently declares pnpm 9.14.4 and Astro 5.12.8, so the build-stage command should match that lockfile contract.

Keep the Docker build context small#

A .dockerignore controls what Docker sends to the builder. At minimum, exclude local dependencies and output that the container will regenerate:

1
node_modules
2
.astro
3
dist
4
.git

Add project-specific generated folders as needed. Do not add a blanket .env* rule without first checking whether your static build requires non-secret, build-time public values. Secrets should not be baked into a static site image: values exposed to client-side JavaScript become public in the generated output.

Docker’s documentation recommends multi-stage builds to separate build-time and runtime dependencies, and .dockerignore keeps unnecessary local files out of the build context. Those are separate safeguards: the first keeps the final image focused, while the second reduces what is available during the build.

Build and verify the container locally#

From the repository root, build the final stage and map its HTTP port:

1
docker build -t astro-static-site .
2
docker run --rm --publish 8080:80 astro-static-site

In another terminal, confirm that the web server is returning the generated HTML:

1
curl --head http://localhost:8080/

Then open http://localhost:8080/ and test one non-homepage route. If the homepage works but a page with a trailing slash returns 404, inspect the corresponding path in dist/ before changing the web-server configuration. With Astro’s usual static output, a route such as /about/ should result in a matching generated directory and index.html.

For a production check, run the same build command outside Docker first. This is especially useful for content collections, image transforms, and search-index generation because it tells you whether the failure belongs to Astro or to the container build.

1
pnpm build
2
test -f dist/index.html

If your site has language-specific output, test one of those paths too. Build an Astro Multilingual Blog Without Migrating Existing URLs includes concrete output checks for /en/ routes.

Do not use this pattern for on-demand routes#

This Dockerfile is for a static Astro deployment. It is not a substitute for an adapter when the site uses on-demand rendering, server endpoints, sessions, or other server-side behavior. Astro’s deployment documentation calls for the appropriate adapter in that case; the runtime image must start the adapter’s server instead of serving a fixed dist/ directory.

That distinction also narrows debugging:

The practical rule is simple: build the static artifact once, copy that artifact into the final image, and verify the generated paths before treating the issue as a hosting problem.

FAQ#