Docker Image

While static export gives you files ready to host anywhere, sometimes you want a self‑contained container image that serves your site with an embedded web server and environment injection. LeadCMS offers a leadcms docker command in the SDK that scaffolds a production‑ready Docker setup for your static site.

Why use Docker?

Packaging your site as a Docker image provides:

• Predictable environment: The OS, web server, caching rules and environment injection are baked into the image. You avoid differences between hosting platforms.
• Easy deployment: Deploy the same image to any container platform (Docker, Kubernetes, ECS, Cloud Run). You don’t need to configure Nginx manually.
• Runtime environment variables: The container injects environment variables at startup so you can build once and configure at deploy time.

Generating a Dockerfile

After running a static build (see Static Export), you can create a Dockerfile with the LeadCMS CLI:

pnpm exec leadcms docker

This command copies a template Dockerfile, an nginx.conf and a small shell script for injecting environment variables into your project directory. The generated Dockerfile typically looks like this:

FROM nginx:alpine

# Copy static site
COPY out/ /usr/share/nginx/html

# Copy Nginx configuration
COPY nginx.conf /etc/nginx/nginx.conf

# Copy environment injection script
COPY inject-runtime-env.sh /usr/local/bin/inject-runtime-env.sh
RUN chmod +x /usr/local/bin/inject-runtime-env.sh

# Define health check
HEALTHCHECK CMD wget --no-verbose --spider http://localhost || exit 1

# Start Nginx with environment injection
CMD ["/bin/sh", "-c", "inject-runtime-env.sh && nginx -g 'daemon off;'"]

The most important pieces are:

• Static files: The contents of your out/ directory are copied into /usr/share/nginx/html.
• Nginx configuration: A custom nginx.conf optimised for static sites is provided. It defines cache headers, handles try_files $uri $uri/index.html =404, and serves 404.html for missing pages.
• Environment injection: At container start, inject-runtime-env.sh scans all environment variables starting with NEXT_PUBLIC_ and writes them into a public/__env.js file. This allows runtime configuration (see Env & Secrets).

Building and running the image

After generating the Dockerfile:

docker build -t my-leadcms-site .

# Pass runtime environment variables when starting
docker run -p 8080:80 \
  -e NEXT_PUBLIC_SITE_URL=https://example.com \
  -e NEXT_PUBLIC_FEATURE_FLAG=true \
  my-leadcms-site

Understanding the Nginx configuration

The generated nginx.conf is tuned for static sites. Key directives include:

• Caching: Static assets (images, CSS, JS) are served with long cache headers. HTML files are served with shorter cache headers to allow content updates.
• Error pages: 404.html is served for unknown routes. You can customise the 404 page in your project.
• Trailing slashes: The try_files $uri $uri/index.html =404; directive ensures that both /about and /about/ resolve correctly when trailing slashes are enabled.

Feel free to adjust nginx.conf to meet your project’s needs. For example, you can enable gzip compression or set specific cache times for certain file types.

Preview server container

LeadCMS also includes a separate preview/Dockerfile for live preview environments. That image starts a Node.js development server alongside Nginx and watches for changes. It’s intended for previewing unpublished content and drafts. For production deployments, use the static Dockerfile described above.

Next steps

Your site is now containerized and ready for deployment. Configure secure environment handling and explore operations: