Developing a Gatsby Site with Docker

Getting Gatsby installed and running can be a challenge. With older versions of Ubuntu I have fought extensively with Node package versions. Docker seems to be a natural solution. This post shows how to build and run a simple Docker image for serving a development Gatsby site.


A Makefile will provide for quicker and easier experimentation.

	docker build -t gatsby-develop .

	docker run -it -p 8000:8000 -v ${PWD}:/site gatsby-develop

There are two targets which can be run as follows:

# Build the Docker image.
make build
# Run the Docker image.
make develop

Helper Script

We’ll use a short BASH script to install dependencies and launch the site.


# Install dependencies.
yarn install
# Serve site.
gatsby develop -H

When first run the yarn command might take some time to gather all of the dependencies. However, they will be installed into a node_modules folder in a shared volume, so this delay will only be incurred the first time that a site is served.

Ubuntu Base Image

I’ve got Ubuntu 23.04 running on my desktop. Installing Gatsby was painless, so the ubuntu:23.04 base image seemed a natural place to start.

FROM ubuntu:23.04


COPY /usr/bin

RUN apt-get update -y && \
    apt-get install -y npm && \
    npm install -g yarn gatsby-cli && \
    chmod u+x /usr/bin/

ENTRYPOINT /usr/bin/

Nothing very fancy happening there:

  1. make a folder on which to mount the site content;
  2. copy the setup script;
  3. update the APT package list;
  4. install NPM;
  5. install Yarn and the Gatsby CLI; and
  6. make the setup script executable and run it.

Node Base Image

But perhaps a full Ubuntu system is excessive? How about a Node base image? The version of Node on my desktop is 18.13.0, so the node:18.13.0 image is a likely candidate. I also tried node:18.13.0-slim as a lightweight alternative.

FROM node:18.13.0-slim


COPY /usr/bin

RUN npm install -g gatsby-cli && \
    chmod u+x /usr/bin/

ENTRYPOINT /usr/bin/

Essentially the same things happening, except there’s no need to mess around with APT or install NPM and Yarn.

Image Sizes

How do the image sizes compare?

  • ubuntu:23.04 — 964.5 MB
  • node:18.13.0 — 1078.3 MB
  • node:18.13.0-slim — 327.8 MB

Somewhat surprisingly the full Node image is larger than the Ubuntu image. But the slimmed down Node image is substantially smaller than either of those.

Test Site

Let’s test this out using a sample Gatsby site.

git clone
cd gatsby-starter-default

Now launch the Docker image to serve the site.

docker run -it -p 8000:8000 -v ${PWD}:/site --name gatsby datawookie/gatsby:18.13.0

The -it options are not strictly required, but I find them useful because it means that I can stop the process with Ctrl-c. You also don’t need to provide a --name argument, but a named container is easier to reference (see below).

I’m using a pre-built version of the image from here. You can grab the underlying code here.

Visiting yields the test site (screenshot below).

If you want to build a production version of the site, then pass the build command.

docker run -v ${PWD}:/site datawookie/gatsby:18.13.0 build

The site files will be dumped to a public directory. You can then serve the site (you’ll find it at

docker run -p 9000:9000 -v ${PWD}:/site --name gatsby datawookie/gatsby:18.13.0 serve


The actions below depend upon you launching a BASH session in a running Gatsby container. Assuming that the container is named gatsby:

docker exec -it gatsby /bin/bash

That will launch a BASH shell in the container with root user.

Compiling Typescript

Running the Typescript compiler will allow you to see any warnings and errors.

yarn tsc

Running Tests

If there are any tests then these can also be run.

yarn test