0003: Docker and nginx

Context#

Not every archive can live on GitHub or GitLab Pages. Internal platforms run containers, and a static site in a container is a solved problem as long as the web server gets three things right: trailing slashes, the 404 page and cache headers for hashed assets. Writing that nginx configuration from memory is where mistakes happen.

Decision#

inkan init copies a Dockerfile, an nginx.conf and a .dockerignore into the repository. The image builds the site in a Node stage and copies dist/ into an nginx:alpine stage. The nginx configuration redirects slash-less URLs to the canonical form, serves 404.html for unknown paths, compresses text and caches content-hashed assets (/_astro/ and Pagefind’s index chunks) forever.

How to use it#

1
docker build -t decisions .
2
docker run --rm -p 8080:80 decisions
3
# http://localhost:8080

The Dockerfile#

1
FROM node:22-alpine AS build
2
WORKDIR /app
3
COPY package*.json ./
4
RUN npm ci
5
COPY . .
6
RUN npm run build
7

8
FROM nginx:alpine
9
COPY nginx.conf /etc/nginx/conf.d/default.conf
10
COPY --from=build /app/dist /usr/share/nginx/html
11
EXPOSE 80

npm ci needs a committed package-lock.json; run npm install once and commit the lock file, or change the line to npm install. Both base images are multi-arch, so the same Dockerfile builds on arm64 and amd64.

The .dockerignore#

1
node_modules
2
dist
3
.astro
4
.git
5
Dockerfile
6
.dockerignore

The build context is the repository without its dependencies and previous output. Note that .git is excluded: inside the image there is no git history, so “Last updated” dates are not shown on pages built this way. Remove .git from the list if you want them, at the cost of a larger context.

The nginx configuration#

1
server {
2
  listen 80;
3
  server_name _;
4
  root /usr/share/nginx/html;
5
  index index.html;
6

7
  absolute_redirect off;
8
  error_page 404 /404.html;
9

10
  gzip on;
11
  gzip_vary on;
12
  gzip_min_length 256;
13
  gzip_types text/plain text/css text/xml application/json application/javascript application/xml application/rss+xml image/svg+xml;
14

15
  location / {
16
    rewrite ^([^.]*[^/])$ $1/ permanent;
17
    try_files $uri $uri/index.html $uri/ =404;
18
    add_header Cache-Control "no-cache";
19
  }
20

21
  location = /404.html {
22
    internal;
23
  }
24

25
  location /_astro/ {
26
    add_header Cache-Control "public, max-age=31536000, immutable";
27
    try_files $uri =404;
28
  }
29

30
  # Pagefind's entry files keep their names between builds; only the index chunks are content-hashed.
31
  location /pagefind/ {
32
    add_header Cache-Control "no-cache";
33
    try_files $uri =404;
34
  }
35

36
  location ~ /pagefind/((index|fragment|filter)/|.*\.pf_meta$) {
37
    add_header Cache-Control "public, max-age=31536000, immutable";
38
    try_files $uri =404;
39
  }
40
}

Behind a proxy or on a sub-path#

The configuration assumes the site is at /. For BASE_PATH=/decisions, build with that variable and move the files into a matching folder in the image, for example COPY --from=build /app/dist /usr/share/nginx/html/decisions, and prefix the two prefix locations (/decisions/_astro/, /decisions/pagefind/); the Pagefind regex location matches under any prefix. See Serve from a sub-path.

To put a login in front of the image, for example with oauth2-proxy, see Protect the site at the edge.

Other servers#

The same three rules translate to any server: redirect to the trailing slash, serve index.html for folders, serve 404.html for misses. On Caddy that is file_server with try_files {path} {path}/index.html and handle_errors; on S3 and CloudFront, an index document of index.html and a custom error response for 404.

Consequences#

• One docker build produces a self-contained image of a few tens of megabytes with no Node runtime inside.
• The image is immutable; a new record means a new image. That matches how the CI pipelines treat the site.
• Without .git in the build context, pages have no “Last updated” date. Trade context size for dates by removing the line.
• Cache headers rely on hashed file names. The HTML itself is no-cache, so a CDN in front must honour that or purge on deploy.
• The files are copied once by init and are yours; later improvements to the starter do not reach existing repositories.