Skip to content
KeystoneJS LogoKeystoneJSv5

Deployment Recommendations

General

Keystone files need to be built with keystone build before running in production mode.

Using Docker

Keystone can be easily built as a Docker container image, suitable for deploying on Kubernetes or other environments.

Recommended guides:

You'll need to add a .dockerignore file to the root of your Keystone project (or wherever the image is built from) to avoid including unwanted files in the image. Here's an example of what it might look like:

.git/
docs/
dist/
.env.secret

If you're already familiar with Heroku or Pivotal Cloudfoundry, you might find Cloud Native Buildpacks a simple way to build Docker images.

The following is an example of production-ready Dockerfile for a Keystone app built with yarn build and started with yarn start:

# https://docs.docker.com/samples/library/node/
ARG NODE_VERSION=12.10.0
# https://github.com/Yelp/dumb-init/releases
ARG DUMB_INIT_VERSION=1.2.2

# Build container
FROM node:${NODE_VERSION}-alpine AS build
ARG DUMB_INIT_VERSION

WORKDIR /home/node

RUN apk add --no-cache build-base python2 yarn && \
    wget -O dumb-init -q https://github.com/Yelp/dumb-init/releases/download/v${DUMB_INIT_VERSION}/dumb-init_${DUMB_INIT_VERSION}_amd64 && \
    chmod +x dumb-init
ADD . /home/node
RUN yarn install && yarn build && yarn cache clean

# Runtime container
FROM node:${NODE_VERSION}-alpine

WORKDIR /home/node

COPY --from=build /home/node /home/node

EXPOSE 3000
CMD ["./dumb-init", "yarn", "start"]

When using Docker for deployment, you'll also need a registry to serve your images. This can be the official Docker Hub, a registry in your cloud provider, a third-party hosted registry, or a self-hosted private registry.

If you have .dockerignore and Dockerfile files in the root of your Keystone project, and you're set up with a registry, you can build and push your image like this:

my-cool-keystone-app$ # Build on local machine
my-cool-keystone-app$ docker build -t my-registry.example.com/my-cool-keystone-app:v1.0 .
my-cool-keystone-app$ # Push to registry server
my-cool-keystone-app$ docker push my-registry.example.com/my-cool-keystone-app:v1.0

You can test running your image locally (no need to push) with a command like this (assuming your server runs on port 3000):

my-cool-keystone-app$ docker run --rm -p 127.0.0.1:3000:3000 my-registry.example.com/my-cool-keystone-app:v1.0

Have you found a mistake, something that is missing, or could be improved on this page? Please edit the Markdown file on GitHub and submit a PR with your changes.

Edit Page