Deploying a PayloadCMS App on Coolify

PayloadCMS is a powerful and flexible headless CMS based on Node.js, ideal for customized projects. As an example: this website itself uses PayloadCMS as a backend to manage content dynamically and efficiently.

Coolify, a platform for deploying web applications and various other services, takes care of all infrastructure management. In this guide, I will walk you through how I host my Payload apps on Coolify step-by-step, covering everything from app preparation to service setup and final deployment.

Combining PayloadCMS and Coolify provides the perfect foundation for developing and operating robust, scalable applications without dealing with complex infrastructure.

Prerequisites

Make sure the following requirements are met:

• Coolify 4 Installation: You need a running server with Coolify 4 installed. An example could be a server from Hetzner. If you haven't set up Coolify 4 yet, you can use the official Coolify setup guide for installation.
• Basic Knowledge of Node.js: Since PayloadCMS is based on Node.js, you should be familiar with the basics of Node.js and your preferred package manager (I recommend pnpm).
• GitHub Repository: Your Payload app should be hosted in a GitHub repository as Coolify uses this for deployment.
• Domain and SSL: Optional but recommended, having your own domain and setting up SSL certificates for your application.

Once these prerequisites are met, you can begin preparing your app and deploying it on Coolify.

Before Deploying on Coolify

Before starting deployment on Coolify, ensure you have a fully functional PayloadCMS app. This guide focuses on deploying the app on Coolify. If you haven't created a PayloadCMS app yet, I recommend consulting the official PayloadCMS documentation to set up an app.

Your app should build locally without issues, and the production build should start without errors. Resolving potential issues locally simplifies the deployment process and avoids complications on the server.

Once your app runs smoothly locally and is hosted in a GitHub repository, you can proceed to the next steps and prepare for deployment on Coolify.

Setting Up in Coolify

Setting up in Coolify is relatively straightforward. Here’s the process I follow:

Creating a Project in Coolify

Open your Coolify instance in the browser and navigate to "Projects." If none exist, create one.

Click on the "production" button and then on "+ Add Resource." Under "Applications," select your preferred method. Since the Coolify instance used here is connected via GitHub Apps, I’ll also use this method. (Connecting via GitHub Apps can be done under the "Sources" menu).

Select the GitHub App, find the desired GitHub repository from the dropdown list, and click "Load repository." Make the appropriate settings and then click "Continue."

Configuring the App

Now configure the Payload app. You can assign a recognizable name, add a description, and specify a custom URL. The most important part here is the Build configuration.

1. Commands: Depending on the build/start scripts defined in your package.json, enter them correctly here.
2. Base Directory: This is specific to your setup. For a monorepo where the Payload app resides in a subdirectory, specify the corresponding path.
3. Publish Directory: This should be the directory with your production build, e.g., /dist.

For illustration:

Database

No Payload app works without a database, so we'll create one directly in Coolify and connect it to the app using a Connection String. Navigate back to Projects -> Your Project -> production (or the environment containing the Payload app).

Click "+ New" under Resources, select your preferred DB (PostgreSQL or MongoDB), and click "Start." Easy as that!

Under the Network tab, copy the connection string (Postgres URL); you’ll need it as an ENV variable for the Payload app.

Setting Environment Variables

Navigate back to your Payload app’s configuration. In the sidebar, click on Environment Variables and add all the variables your Payload app requires.

Important: Ensure the "Build Variable?" checkbox is checked. If you’ve used the Developer View to manage your ENV variables, switch back to Normal View and check the box!

Persistent Media Uploads

If you’ve followed all the steps so far, you’re ready to deploy the app. However, here’s a tip if your Payload app uses media uploads.

To prevent uploads from being lost between deployments, navigate to Storages under Environment Variables.

Click "+ Add", enter a name and a destination path under Volume Mount. For example, the upload directory (/media) in my Payload app is in the root directory. Note: /app/ is the root of the Docker container where the app runs.

Deploying the App on Coolify

Now, we can (try to) deploy the Payload app. Simply click "Deploy." You’ll automatically be redirected to the Deployment page to monitor the process. For detailed deployment logs, click on "Show Debug Logs."

If an error occurs during deployment, you can identify and fix the issue through the logs.

Conclusion

With this guide, you’ve learned the key steps to successfully deploy a PayloadCMS app on Coolify. Combining these two powerful tools allows you to manage and scale complex web applications with minimal effort. Coolify handles infrastructure management, while PayloadCMS provides maximum flexibility for creating and managing content.

Once this process is set up, you can deploy future versions of your app quickly and easily, ensuring your application is not only live but also secure and reliably hosted.

I hope this guide has been helpful and that you now have a better understanding of deploying your PayloadCMS app on Coolify.

Good luck with your deployment and development projects!