Preparing a Gatsby site for production with Docker and Nginx

Gatsby is a fantastic tool for those of us who find React syntax familiar, but want to create simple static pages. Its community is large and active, and getting started in development requires little investment. Yet going to production -- especially when considering including a Gatsby project in an existing codebase -- can be another story. Gatsby comes with a gatsby start command that runs the production build on a Node server, and it is easy to misinterpret this as the proper way to serve Gatsby pages in production. By using Docker and Nginx to serve a production Gatsby site, pages can be compressed and served in gzip format, optimized for SEO, and ingtegrated into an existing project incrementally.

---

Go ahead and just get the source code here.

---

Getting started

This tutorial is going to assume you already have some experience working with Gatsby and already have an existing site. If not, a very easy way to do this is by using npx with npx gatsby new <your-site-name>, as detailed here.

Building pages

Right now, the only way you can build and run this site is with the help of Gatsby running a server for you. The first step in creating a production-ready Nginx server is adding a Dockerfile at the root of your project. The first stage of this multi-stage Dockerfile will handle building the production pages of your site.

FROM node:alpine

COPY . .

# System dependencies for packages that use node-gyp
RUN apk add --update --no-cache \
  python \
  make \
  g++

RUN npm install && npm run build

To ensure that this is working properly, run docker build . -t my-gatsby-site from the same location as the Dockerfile. Now we need to create our server.

Nginx

Nginx is open-source software that powers a large portion of the internet's web servers¹. While it provides many features, it is also incredibly simple to get up and running. In order to get started, create a file nginx.conf in the root of the project and add the following code:

server {
    listen 80;
    server_name _;

    root /var/www/;
    index index.html;
}

In order to run this server in Docker, we need to add to our Dockerfile:

FROM node:alpine as gatsby-pages

COPY . .

RUN apk add --update --no-cache \
  python \
  make \
  g++

RUN npm install && npm run build

FROM nginx:stable as release

COPY --from=gatsby-pages public /var/www/
COPY ./nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

In order to have multiple stages that can reference each other, we alias our initial Gatsby build as gatsby-pages. The static files that are built in the initial step are then copied to var/www in the release build, where our Nginx config is expecting them. Now we can rebbuild the container:

  docker build . -t my-gatsby-site

And then run it:

  docker run -p 80:80 my-gatsby-site