Deploying Payload CMS

Payload CMS is a headless CMS and application framework built with TypeScript, Node.js, React and MongoDB.

In this guide, you will learn how to set up a new instance of Payload CMS with MongoDB on Northflank, and optionally also configure a persistent volume for file uploads.

1. Create a fresh installation of Payload CMS using npx create-payload-app or following the manual installation documentation.

   • During the installation, you can choose whether you want to use JavaScript or TypeScript.
   • You can keep the default MongoDB connection as we will change it later using environment variables.
   • You can use our random key generator (in secret groups) to generate a long and secure string to use as Payload’s encryption key.

2. Navigate to your config file (payload.config.js or /src/payload.config.ts) and update the below line:

   // ...
   serverURL: 'http://localhost:3000',
   // ...

   Replace 'http://localhost:3000' with process.env.PAYLOAD_PUBLIC_BASE_DNS to inherit the server URL from an environment variable. This will ensure your Payload instance works correctly when deployed to production.

   // ...
   serverURL: process.env.PAYLOAD_PUBLIC_BASE_DNS,
   // ...

3. Open your .env file and add the following line to set the new environment variable:

   PAYLOAD_PUBLIC_BASE_DNS=http://localhost:3000

4. Add a new file called Dockerfile (without extension) to the root of your project. Dockerfile will specify what commands are run when building and deploying your application and this will ensure a successful production deployment. Copy and paste the below code to your Dockerfile:

   FROM node:12-alpine AS builder
   
   ARG PAYLOAD_PUBLIC_BASE_DNS
   
   RUN mkdir -p /app
   WORKDIR /app
   
   COPY package.json  .
   COPY yarn.lock .
   
   RUN yarn install
   
   COPY . .
   
   RUN yarn build
   
   EXPOSE 3000
   CMD [ "yarn", "run", "serve" ]

5. Commit all files (except node_modules and .env) and push to a new Git repository.

6. Create a new combined service in a new project on Northflank and select your repository as the source. Under build options, select Dockerfile and verify your Dockerfile exists. Port 3000 will be detected automatically and exposed by default.

7. Create a new MongoDB database. For increased security, keep SSL enabled and External Access disabled. You can start with the smallest compute plan with 4 GB of storage and one replica.

8. Create a new secret group in your project and link the database. Then inherit the environment variable mongoSrv as an alias MONGODB_URI.

   

   • Inheriting environment variables ensures that the database connection details are automatically injected in the environment, avoiding the need to manually copy and paste them.

   Add the following manual secrets:

   Key	Value
   PAYLOAD_PUBLIC_BASE_DNS	The unique service code.run deployment URL or a linked custom domain (prefixed with https://)
   PAYLOAD_SECRET	Your secret string set during the installation
   NODE_ENV	production

   

   • The secret group is set to type Environment & Arguments by default. This means the secrets will be available both during build and deployment.

9. Navigate back to the service and initiate a new build by clicking on the icon on the latest commit. Once the build is finished, a new deployment will start and your Payload CMS will be available shortly. You can navigate to the service URL followed by /admin to get started.

Licensing and Uploads with Volumes

To use Payload CMS in production, you also need to add a licence key. Read more about how you can obtain one in the official Payload documentation.

Once you have your licence, you will need to adjust the server.js file and add the license key as an environment variable.

Northflank supports persistent volumes and can therefore be used to store your uploads. You just need to configure your upload folder under Volumes in the service sidebar.