This tutorial provides a step-by-step guide for deploying a Strapi application using Dokku and DigitalOcean.

This tutorial covers everything from installing Dokku and creating a new app to configuring SSL with Let's Encrypt and setting up auto-deployment on GitHub. Following these instructions, you can deploy and manage web applications, databases, and other services on your servers or cloud providers like DigitalOcean.

What is Dokku?

Dokku is a Docker-powered PaaS that helps you build and manage the lifecycle of applications. It is designed to be a lightweight and simple alternative to Heroku.

You can think of it as a self-hosted Heroku that you can deploy on your own infrastructure. With Dokku, you can easily deploy and manage web applications, databases, and other services on your own servers or cloud providers like DigitalOcean.

Note: To give some heads-up, if you are looking for cheap hosting, we know it works. Simen would recommend Contabo. The server comes with the following:

• 200GB SSD Space or 50 GB NVMe
• 8GB RAM
• Four vCPU Cores

Affiliate Link here. This is not recommended by Strapi but personally by Simen Daehlin.

👷‍♀️ Prerequisites

• Strapi Project
• min 2GB Ram (4GB+ Recommended)

🥷 Server Setup

Sure thing! Here's a step-by-step guide for setting up a droplet on DigitalOcean:

1. Log in to your DigitalOcean account and click on the Create button in the top right corner of the dashboard.
2. Select Droplets from the dropdown menu.
3. Choose a hostname for your droplet.
4. Select the size of your droplet. Strapi does recommend a *min of 2GB of RAM. Dokku itself requires min of 1GB of RAM*
5. Choose a data center region closest to your target audience.
6. Select Ubuntu 22.04 LTS as your droplet's operating system. (Important here is not to use xx.10 as it won’t work)
7. Choose any additional options you need, such as backups or monitoring.
8. Click Create Droplet to finalize your settings and create your droplet.

Once your droplet is created, you can access it via SSH and set up your server. Let me know if you have any other questions!

🔐 Important About SSH

Note: Please note that to use Dokku, we need an SSH Key. If you don’t have one, please make sure you create one. You can find out how to do it here. Windows MAC / Linux (Unix)

⚠️ Please note that the commands here assume you are SSH’ed into the box itself.

🐳 Install Dokku

To install Dokku, you can use a one-line command provided in the official Dokku documentation. SSH into your server and run the following command:

wget -NP . https://dokku.com/bootstrap.sh
sudo DOKKU_TAG=v0.30.9 bash bootstrap.sh

This command will download and run the Dokku installation script, which will install Dokku on your server. Make sure you have about SSH to your server before proceeding with the installation.

Once the installation is complete, you can access the Dokku web interface by navigating to http://your-server-ip in your browser. From there, you can configure your server and deploy your applications.

Now, please ensure you have your SSH at hand, as we need this.

PUBLIC_KEY="your-public-key-contents-here"
echo "$PUBLIC_KEY" | dokku ssh-keys:add admin

🍏 Creating an Application

To create a new app named mystrapi, run the following command in your Dokku server:

dokku apps:create mystrapi

💾 Creating Postgres database

sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git

Once the plugin is installed, create a new PostgreSQL instance named "strapi" by running:

dokku postgres:create strapi

To link the PostgreSQL instance to your app, run the following command:

dokku postgres:link strapi mystrapi

⚠️ Please take note of the username and password that get printed out, and save them if we need them for later. The line you are looking for is DSN, and it’s written like so ”postgres://DATABASE_USERNAME:DATABASE_PASSWORD@DBHOST:DATABASE_PORT/DATABASE_NAME”

⚙️ Configure Dokku and Strapi Environmental Variables

This is a oneline code for you to set HOST, PORT, APP_KEYS, API_TOKEN_SALT, ADMIN_JWT_SECRET, JWT_SECRET

dokku config:set mystrapi HOST=0.0.0.0 PORT=1337 APP_KEYS="$(for i in {1..3}; do openssl rand -base64 16; done | tr '\n' ',')" API_TOKEN_SALT=$(openssl rand -base64 32) ADMIN_JWT_SECRET=$(openssl rand -base64 32) JWT_SECRET=$(openssl rand -base64 32)
dokku config:set mystrapi DATABASE_USERNAME=INSERT FROM OUTPUT ABOVE DATABASE_PASSWORD=INSERT FROM OUTPUT ABOVE DATABASE_PORT=INSERT FROM OUTPUT ABOVE DATABASE_HOST=INSERT FROM OUTPUT ABOVE DATABASE_NAME= INSERT FROM OUTPUT ABOVE

🌎 Optional: Setup Domain

Next, you need to set up a domain for your app. Run the following command to add a domain:

dokku domains:set-global example.com
dokku domains:add mystrapi backend.example.com

Replace "example.com" with your desired domain name.

🔐 Setting up SSL and Let’s Encrypt

To configure Let's Encrypt for your app, you need to install the Let's Encrypt plugin by running:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Once the plugin is installed, you can enable Let's Encrypt for your domain by running the following command:

dokku letsencrypt:set --global email <your-email>
dokku letsencrypt:enable mystrapi
dokku letsencrypt:cron-job --add

Replace <your-email> with your email address.

That's it! You have now created a new app, installed PostgreSQL, linked it to your app, added a domain, and configured Let's Encrypt. You can now deploy your app by pushing your code to your Dokku server.

🚒 Configure the Proxy

When you deploy Strapi using Dokku, it is important to note that Dokku uses a proxy to route requests to the correct port on the container (remember, each app is a container in Dokku). Strapi uses port 1337, so to use Strapi with Dokku, we need to configure the proxy to route ports 80 and 443 to port 1337.

To do this, we can use the dokku proxy:set command with the appropriate arguments. Specifically, we need to specify the name of our app on Dokku and the ports that we want to proxy to port 1337. The command to configure the proxy for Strapi would look like this:

1
dokku proxy:set mystrapi http:80:1337 https:443:1337

Here, mystrapi should be replaced with the name of your app on Dokku. Once this command is executed successfully, Dokku will route requests from ports 80 and 443 to port 1337

🚀 Auto Deployment with git

1. Create a new file in your repository called .github/workflows/deployment.yml with the following contents:

    name: Deployment
    on:
      push:
        branches: [main]
    jobs:
      build:
        name: Deploy to Dokku
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v2
            with:
              fetch-depth: 0
          - name: Dokku Deployment
            uses: dokku/github-action@master
            with:
              git_remote_url: "ssh://dokku@${{ secrets.HOST }}:22/APPNAME"
              ssh_private_key: ${{ secrets.SECRET }}
              git_push_flags: "--force"
            env:
              BUILDER_ENV: production

Replace APPNAME with the name of your app on Dokku.

2. To add the SECRET and HOST secrets, go to your repository on GitHub and click on Settings > Secrets > New repository secret. For Name, enter SECRET. For Value, paste in your SSH private key. Repeat the process for the HOST secret, with the value being the IP address or domain name of your Dokku server.o add the SSH private key to Dokku, SSH into your server and run the following command

👔 Manually Push to Dokku

You can do the following if you don’t want to automate the deployment and just push.

1. In your Strapi project, add the Dokku server as a repo.

git remote add dokku ssh://dokku@IP-ADDRESS-OR-DOMAIN-TO-DOKKU:22/APPNAME
git push dokku

Or you can use git sync if you already have a public repo. This will have Dokku PULL directly from GitHub or other repositories.

⚠️ Please note: The repo has to be public

dokku git:sync --build mystrapi https://github.com/GITHUBUSERNAME/REPONAME.git

Now the last bit we need to do is that GitHub changed branches a few years ago from master to main, so we must tell Dokku that we want to adhere to this.

dokku git:set --global deploy-branch main

You can also remove --global and set it per app if you use a different branch.

🐳 Using Our Own Dockerfile (Optional)

As you noticed, people might have issues. We also cover setting up Docker to use your Dockerfile instead of using herokuish. Using a Docker file means we know the environment that gets created always will be the same and won’t change.

Creating a Dockerfile to use with Strapi is quite easy with Strapi Community Dockerize Tool.

1. In your project, run npx @strapi-community/dockerize@latest
2. Select your Package Manager yarn / npm
3. Select NO to use docker-compose
4. Select Production
5. Done 🎉

Now that we created the Dockerfile, we can tell Dokku that we want it to build for this project.

In your Dokku server again

dokku builder-dockerfile:set mystrapi Dockerfile.prod

This tells Dokku to look for a prod file. If you only have a Dockerfile, you don’t need to specify it. Dokku is smart enough to auto-detect it.

👷‍♂️Dockerfile Build Arguments

As our Dockerfile we want to specify the build argument like NODE_ENV. We can tell it to always build for production or override it to whatever we want. We run the following command on the server

dokku docker-options:add mystrapi build '--build-arg NODE_ENV=production'

If you previously used the guide and tried to deploy with herokuish we need to RESET it to use Docker.

First, let’s get the build pack URL that was set.

dokku buildpacks:report mystrapi

Then let's remove it, you are looking for Buildpacks list and copy the URL:

dokku buildpacks:remove mystrapi INSERT URL FROM BUILDPACKS ABOVE
// Example
dokku buildpacks:remove mystrapi https://github.com/heroku/heroku-buildpack-nodejs.git

When you now deploy, it should use a Dockerfile instead of herokuish. Please check their documentation on this here.

🎁 Wrap up

This tutorial taught you how to deploy a Strapi application using Dokku and DigitalOcean. Dokku is a Docker-powered PaaS that helps you build and manage the lifecycle of applications.

We covered how to install Dokku, create a new app, install PostgreSQL, link it to your app, add a domain, configure SSL with Let's Encrypt, configure the proxy, and set up auto-deployment on GitHub.

We also provided instructions for manually pushing to Dokku. With this knowledge, you can easily deploy and manage web applications, databases, and other services on your own servers or cloud providers like DigitalOcean.

Overall, deploying a Strapi application using Dokku and DigitalOcean is a straightforward process that can be completed in just a few steps. By following the steps outlined in this tutorial, you can set up a scalable, reliable, and secure server for your Strapi application.