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
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.