Heroku, simple deployment guide

[quornik]

Simple guidelines how to deploy PayloadCMS to Heroku (TYPESCRIPT)

Because as you might find further down in this note, I was a bit confused how to deploy PayloadCMS to Heroku, then I went thru the process and decided to share few important highlights, for others to avoid struggle and confusion:

TASK

• Succesfully deploy your payload installation to Heroku, and maintain stable & working Payload installation locally.

Important, Heroku specific details

• Heroku assigns port to your installation dynamically, and sets it in hidden ENV_VAR, named simply PORT.
• Heroku does not recognize serve script command, but it does recognize start, so for Heroku purpose, you need the latter doing (almost) exactly the same as former.
• In original serve provided by basic PayloadCMS, there is a series of important deploy changed to ENV_VARS, executed with the use of cross-env. But, cross-env is devDependency, and as such is omitted by Heroku during start. So simple copy / paste of the same command form one to another will not do the trick.
• You might ofcourse put cross-env in to the dependecies and go on with that, but this is not an elegent solution, and non-elegant solutions tend to create problems furter down the road so...

Final changes

/src/server.ts
CHANGE

app.listen(3000)

TO

app.listen(process.env.PORT || 3000)

/package.json script should contain "start" like this:

"scripts": {
    ...
    "serve": "cross-env PAYLOAD_CONFIG_PATH=dist/payload.config.js NODE_ENV=production node dist/server.js",
    "start": "node dist/server.js",
    ...
  },

AND for this to work, you need these Enviroment Variables set accordingly in Heroku app:

PAYLOAD_CONFIG_PATH=dist/payload.config.js
NODE_ENV=production

The domain / serverURL

Next, You want to change the serverURL in /src/payload.config.ts | /payload.config.js for it to contain your production domain. ( this part is equally related to typescript nd javascript installation)

• In original PayloadCMS config file, the serverURL is hardcoded as http://localhost:3000.
• It WILL NOT WORK this way on production, and you need to remember to change it to the production domain name.
• To maintain your work stable locally and in production enviroment, you do not want to "juggle" the hardcoded domains, so the best approach is to use ENV_VARS. But there is a catch...
• Payload expects You to provide specifically named vars, which start with PAYLOAD_PUBLIC_. It is ONLY for the payload.config.js | payload.config.ts files, for server.js | server.ts it is not necessery.

Final changes

/env.payload.config.ts

import { buildConfig } from 'payload/config';
import dotenv from 'dotenv';
import path from 'path';
import Users from './collections/Users';
import Admins from './collections/Admins';

dotenv.config();

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL || 'http://localhost:3000',
  cors: "*",
  rateLimit: {
    trustProxy: true
  },
  admin: {
    user: Admins.slug,
  },
  collections: [
    Users,
    Admins,
  ],
  typescript: {
    outputFile: path.resolve(__dirname, 'payload-types.ts')
  },
});

And of course the Enviroment Variable on heroku:

PAYLOAD_PUBLIC_SERVER_URL={your-domain-adress.com}

Note: In my installation Admins collection is the one containing administrators. Be not confused, if your standard PayloadCMS config has users in this place.
In this setup I also put trustProxy to true, and cors to all, for testing purposes. Since Heroku works in dynamic enviroments, truspProxy propably is necessery, but if you find your installation working without it, please be kind and make note about it.

DISCLAIMER: This guide is typescript related. Deploying with javascript version of Payload installation is much simpler, and consist only of changes to package.json and adding script: "start": "node server.js" and adding ENV_VAR on Heroku NODE_ENV=production. DO NOT add the second var, as it will crash the build.

Thats it. Enjoy!

Here's a part om my original note in this thread:

Can anyone share or maybe point me in to right direction which I should look into: A comprehensive guide to Payload CMS production deployment, on services like Heroku or Netlify?

(...)

I would really appriciate somew help.

[denolfe]

Awesome post @quornik 🙌

We can look into officially documenting this process. This will help a lot in that effort 👍

[quornik]

hey @denolfe , As I just ended refactoring my project from typescript to javascript, I realised that whole lot of the struggle in deploying to Heroku is typescript related. I've updated the article with disclaimer that it is typescript specific, and how to simply approach the subject with js installation - it's much simplier.

[aaronksaunders]

was this ever added to the documentation? Do you know if there is anything more recent? I am about to give this a try since I couldn't find any other documentation @denolfe

[iPrincey]

Thanks a lot, man!
You're a life saver.
THIS SHOULD DEFINITELY BE INCLUDED IN THE OFFICIAL DOCS.