← Back to Guides
Profile image for Thomas Smyth

By Thomas Smyth

Published 22nd April 2022

Deploy KeystoneJS on Northflank

KeystoneJS is a free open-source content management system or app framework that allows you to quickly build a scalable GraphQL API and beautiful management user interface for your content and data simply by describing your schema. This guide will show you how to create a new KeystoneJS project and deploy it on Northflank. The full source code used in this guide can be found in this Git repository.

Initiate the KeystoneJS Project

To start, we must initiate a new KeystoneJS project from KeystoneJS’s starter kit and push it to a Git repository on a Git provider linked to your Northflank account to allow Northflank to access it.

  1. Initiate a new KeystoneJS project by running npm init keystone-app and inputting the information requested by the command line interface.

  2. Initiate a new Git repository for your project by running git init within the folder created in the previous step.

  3. Create a new Git repository on a Git provider linked to your Northflank account.

    • For more information on how to link a Git account to your Northflank account, check out our documentation.

  4. Link your local Git repository with the Git repository on the Git provider by running git remote add origin <Your Git repository URL>.

  5. Commit your new project.

Configure Database Connection & Migrations

KeystoneJS uses Prisma to interact with a database that stores your content and data, as well as Prisma Migrate to apply changes to your project’s schema to the database. However, before we can make use of this, there is a little more configuration that needs to be done.

  1. Configure KeystoneJS to read the connection details for the Postgres database we will store our content and data in from the runtime environment by setting db.url to <string>process.env.DATABASE_URL and db.provider to ’postgresql’ in the config section of the keystone.ts file in your project.

  2. Configure KeystoneJS to use migrations by also setting db.useMigrations to true.

  3. Configure KeystoneJS to run migrations before starting the app by updating the start command in the package.json file to keystone prisma migrate deploy && keystone start.

    • Configuring KeystoneJS to run migrations before starting the app ensures that the database’s schema always matches that expected by the version of the app that is about to be executed. This is especially important if you have multiple different environments where the version of the app may be executed, for example, if you promote the version of the app from a staging to a production environment via a pipeline.

  4. Deploy a Postgres instance locally, or deploy a Postgres addon on Northflank and forward to it with the Northflank CLI, to use in the following steps and whilst developing your project.

  5. Set an environmental variable with the key DATABASE_URL to the connection URI of the database created in the previous step.

  6. Create the initial migration by running yarn run dev.

    • When changes are made to the KeystoneJS schema whilst running yarn run dev you will be prompted to create a migration that synchronises the database’s schema to match the changes.

  7. Commit the changes to your project.

Configure Docker

To deploy your new project on Northflank, we must configure a Dockerfile that defines the environment the KeystoneJS app will run in.

  1. Create a new file called Dockerfile that contains the following:

    # https://docs.docker.com/samples/library/node/
    ARG NODE_VERSION=16.13.2
    # https://github.com/Yelp/dumb-init/releases
    # Build container
    FROM node:${NODE_VERSION}-alpine AS build
    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
    RUN 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"]
  2. Commit the changes to your project and push them to the Git repository on your Git provider.

Deploy to Northflank

Now we have initiated our KeystoneJS project, we can now deploy it to Northflank.

  1. Create a new Postgres addon.

    Addon creation deploying KeystoneJS to Northflank

  2. Create a new secret group.

    1. Add the key SESSION_SECRET and set its value to a random secret.

      • To bring up a tool to generating random secrets, click the key symbol at the top right of the secrets section of the form.

    2. Link the POSTGRES_URI variable from the Postgres addon created in the previous step and assign it the alias DATABASE_URL.

    Secret group creation and linking to the Postgres addon

  3. Create a new combined service with the following configuration.

    1. Repository as the Git repository you pushed your project to.

    2. Build type as Dockerfile.

    3. Resources: It’s recommended to use plan nf-compute-50 or larger to ensure appropriate app performance.

      • Port 3000 will automatically be detected from the image manifest and will be exposed with the HTTP protocol.

    Service creation to deploy KeystoneJS on Northflank

  4. Wait for your project to be built and deployed, then open the web interface by clicking on the link in the top right corner of your service.

    • It will take approximately a minute for the KeystoneJS instance to start up.

  5. On the initial KeystoneJS page, you will be asked to create a user. Once you have created a user, you will be able to start creating content and data!

If you encounter any issues while following this guide we're happy to assist you with your KeystoneJS deployment at support@northflank.com. At Northflank we also have dedicated support plans for business customers.

Demo video:

Using Northflank to deploy your KeystoneJS application

Northflank allows you to deploy your code and databases within minutes. Sign up for a Northflank account and create a free project to get started.

  • Connect with your preferred VCS: GitHub, GitLab or Bitbucket
  • Manage build arguments and environment variables using secret groups
  • Scale vertically and horizontally with multiple replicas per service
  • Observe & monitor with real-time metrics & logs
  • Low latency and high performance
  • Create pipelines and release workflow as you grow
  • Dedicated support plans

Share this article with your network