Deploy Node.js applications on a VPS using Coolify

If you are not a DevOps person, deploying applications is not going to be very easy if you are trying to do everything on your own. This is the primary reason we have a lot of managed offerings from companies like Heroku, Vercel, Fly etc.

Managed offerings make it extremely easy to deploy applications on the Internet. They eliminate the hassle for us, but this convenience comes at a cost. Recently there has been a lot of noise around the self-hosting vs managed hosting.

My VPS configuration

I’ve been hosting all my APIs for applications like Flagsy, Flare, Compito, etc on a VPS with the following configuration:

1. 1 vCPU

2. 2GB RAM

3. 40GB Storage

4. Ubuntu

Worked well for my use case. The VPS cost me around $7 per month. I’ve now shifted to a new VPS from Oracle which provides a great config in their free tier.

1. 4 vCPU

2. 24GB RAM

3. ARM Based

4. Ubuntu

Deployment workflow before Coolify

For all these years, I’ve been using GitHub Actions with a custom workflow for deploying applications to the server. The GitHub Action workflow is as follows:

1. Build the Application.

2. Package the contents into an artifact (.tar file).

3. Send the artifact to the remote server using rsync (ref: How to use Rsync to Sync Local and Remote Directories)

4. SSH into the remote server.

5. Extract the contents of the .tar file.

6. Install Dependencies.

7. Run the application using PM2 (ref: Process manager for Node.js)

Deployment using Coolify

When I came across Coolify, I thought of giving it a try. I am aware of Dokku, but I never really tried it because it doesn’t have a UI. I work primarily as a UI developer, so having a nice UI to work with is a plus for me.

Coolify is an open source & self-hostable Heroku / Netlify / Vercel alternative. Built by Andras Bacsai (@heyandras)

It’s surprisingly good. I did feel a bit lost when I first started trying it out. Eventually, everything fell into place, and I’ve moved all my previously hosted node applications to use Coolify instead.

Getting started with Coolify

To get started, you need a server, it can be a VPS, a Raspberry Pi, or any other server that you have SSH access to.

Coolify comes with a pretty neat one-click installation script which makes the installation super easy.

Minimum requirements for Coolify

VPS offerings that I found to be good:

• Hetzner

• OVH

I’ve used both of these and didn’t have any issues with them.

Installing Coolify

The first step is to SSH into your server.

ssh <username>@<ip_address>

Once you are inside the VPS. Enter the below command to install Coolify

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

If you get an error saying: Please run as root using the command below:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Once the installation is complete, you’ll get a link to the Coolify dashboard. When you visit the link (Eg: http://<server_ip>:8000), you’ll be asked to register yourself.

Localhost vs Remote Server

On completion of registration, we will come to this screen where we need to choose whether we want everything to be on one server or not.

If you want to host Coolify on one server and deploy the applications on a different one, go with the Remote Server option. Else continue with Localhost.

I am using the Localhost mode. In the next step, server requirements are validated. Once validation is complete, we can get started by creating our first project.

Resources

We can host multiple resources in the server like Applications, Databases and Services. Each of these are called as a resource in Coolify.

Coolify supports deployment of applications from your private GitHub repo or any public repo. You can also deploy using Docker.

When it comes to databases, we have out of the box support for popular databases like PostgreSQL, MySQL, Mongo, Redis etc.

Deploy Node application using Coolify

There are couple of ways in which we can deploy a node.js application. We will be looking at how to deploy a node application on Coolify using Nixpacks.

Deploy using Nixpacks

This one will be the easiest way to deploy any node application using Coolify. The whole process is pretty straight forward.

Nixpacks takes a source directory and produces an OCI compliant image that can be deployed anywhere.

In simpler terms, Nixpacks will analyse the source folder and automatically create a Dockerfile for us. We don’t have to know anything about docker.

We are going to be building a super simple Notes API using:

Setting up the MySQL database

Under Project > Environment > Resources > + New > Databases, you’ll be able to see MySQL. Start by adding a database into your project.

All the necessary information is prefilled, and we are good to go. Clicking on Start will spin up a docker container. Wait for the process to complete and once done, the status would say Running.

Deploying The Node Application

For deploying our node application, we start by adding a new resource to your project by going to Project > Environment > Resources > + New > Public Repository

Continue till we are asked to provide the URL of the repo:

https://github.com/adisreyaj/notes-api

Once Coolify loads the repo, we’ll be asked to create a new application. We choose Nixpacks as the Build Pack and use 3000 for the port to run the app on.

Configure environment variables!

We need to configure the environment variables that are consumed by our application. Navigate the Environment Variables page and start adding the following variables.

If you are using Prisma, we need to expose the database to the internet. Some applications / libraries need to connect to the database during the build phase, to run migrations for example. Ref: Frequently Asked Questions (FAQ) with Coolify

Copy the MySQL URL(Public) in case you are using Prisma or copy the MySQL URL(Internal) URL in other cases.

mysql://mysql:BfwAmHtmTokbm70fUoFcsL7obNMPCFcW@vww348go4:3306/default

We can split the database URL into the below environment variables:

DATABASE_HOST=vww348go4
DATABASE_NAME=default
DATABASE_PASSWORD=BfwAmHtmTokbm70fUoFcsL7obNMPCFcW
DATABASE_PORT=3306
DATABASE_USER=mysql
PORT=3000

You can either add all of these variables at once using Developer View or create them individually.

There is an option called Build Variable which will make the env available during build phase. For this particular example, we don’t need to check the option. But for Prisma and other libraries, we need to make the environment variables accessible at build time.

Deploy the application!

Once we have configured the env variables, we can go ahead a Deploy the application. Coolify shows the logs of the process, we can click on Show Debug Logs to see detailed logs.

Once the application is deployed successfully, we can view the logs of the application under the Logs tab.

You should be able to visit the domain provided and see the app live.

Troubleshooting

Providing custom commands

If you think that Nixpacks picked wrong commands for install, build, or start, you can customize it in the Configuration > General section.

Database not reachable

If you see any errors related to database not reachable, make sure to double check the env variables and make sure they are correct.

Also, if you are using Prisma or other libraries which might access database at build time, make sure to mark the environment variables as Build Variable.

For Prisma with Nixpacks, we need to make the database publicly accessible over the internet.

Feel free to reach out to me if you are having trouble in deploying using above mentioned steps. Happy to help.

Connect with me

Have any thoughts or questions? shoot’em below in the comments.
Stay Safe ❤️