How to deploy your backend to production with Dokku

Step-by-step Dokku backend deployment for Node.js, FastAPI, Django or similar apps: server setup, SSH keys, domains, env vars and GitHub Actions CI/CD.

How to deploy your backend to production with Dokku
  • Imagine that you've created a backend app on Node.js, FastAPI, Django or any other framework and now you want to deploy your fancy endpoints to the world. I'll show you the step-by-step guide on how to do it with Dokku - open source PaaS which acts like a CLI & Free version of Heroku. Let's go!

    We will also create a CI/CD pipeline which will trigger the deploy after each commit on main branch. What a miracle!

    1. Install Dokku on a machine

    Check https://dokku.com/ for Dokku latest installation instructions.

    2. Add your ssh keys

    You've probably should already done that on the previous step. Read more about dokku ssh-keys.

    echo "$CONTENTS_OF_YOUR_PUBLIC_SSH_KEY_HERE" | dokku ssh-keys:add KEY_NAME

    You will need to send your SSH private key to Github's encrypted storage because Github Actions need to have an SSH access to your machine to trigger the deploy. You also can create a new SSH pair to keep your own's in secret.

    3. Create Dokku app

    Let's call your backend app just api.

    dokku apps:create api

    4. Set environment variables

    Your app probably needs some envs to start. If you are deploying an open-source project, the repo probably should have a file like .env.example which states all the env variables required for the app to run.

    dokku config:set api ENVIRONMENT=PRODUCTION TOKEN=asdadgs ...

    You can also see all set env variables using dokku config:show api command.

    5. Create databases (postgres, redis, ...)

    If your app needs a database you can install them using Dokku plugins. Check for example dokku-postgres plugin, read its readme and feel that it is so much easier to use rather than deploying a database on your own.

    dokku postgres:create api
dokku postgres:link api api

    I called the database with the same name as my dokku app api  for simplicity. The postgres:link comman sets DATABASE_URL .env variable with a connection string to your database.

    If you need to have a Redis plugin you can create and link it the same way (after installation):

    dokku redis:create api
dokku redis:link api api

    Redis will create .env called REDIS_URL. Cool, huh?

    6. Attach a domain to an app

    If you want your api to run on api.yourdomain.com first of all you need to open your DNS provider (where you have bought your domain) and create a DNS "A" record which points api.yourdomain.com to the IP address of your server.

    I personally like to transfer the DNS nameservers to Cloudflare because it has a nice UI and cool features built-in.

    dokku domains:set api api.yourdomain.com

    If you need to sercure your backend with https, check dokku-letsencrypt plugin.

    7. Set SSH_PRIVATE_KEY in Github repo

    Open your Github repo's settings and set the SSH_PRIVATE_KEY in Settings -> Secrets and Variables -> Actions. You need to specify the private key which has the ssh access to the server. Github Actions worker will connect to your server and trigger the deploy, as simple as that.

  • 8. Create Github Actions workflow file

    There are multiple Github Actions plugins for Dokku available but I like to use this one. Copy it to .github/workflows/dokku.yml of your repo and specify your machine host & dokku app name inside.

9. Send a commit  and check Github Actions for deployment logs.

~~ viola ~~

~~~ you've dome a great job ~~~

Please share this page with your tech friends.

My links: