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.

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.

   • Not familiar with Git? Check out GitHub’s Git Guide.

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.

   • For more information on database migrations, check out KeystoneJS’s documentation.

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
   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
   
   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"]

   • This Dockerfile, based of an example provided in KeystoneJS’s documentation, will build your project and then copy the built project to a new Docker image ready to be executed.

2. Commit the changes to your project and push them to the Git repository on your Git provider.

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

1. Create a new Postgres addon.

   

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.

   

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.

   

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: