I have some side projects that don’t see much traffic so I run them on a 5$ Digital Ocean droplet running Dokku.
Dokku is an open source Heroku-like platform. It’s super easy to create and maintain multiple applications on a Dokku instance. It's perfect for solo makers.
There are plugins for most of the common services you might want like PostgreSQL or Redis.
Here's what we're going to do
- A Brief overview of Dokku
- How to get a Dokku instance running
- Create a new Dokku application
- Add a database service
- Expose the database for debugging and testing (Optional)
- Add a domain to the application
- Add any configuration variables for your application
- Add SSL to the application
- Add the Dokku remote to your application
- Push your application to Dokku
- Maintaining your Dokku server
1. Why Dokku?
I don’t have the time to worry about infrastructure for any personal projects and I don’t want to learn new tech for them. Dokku wraps up managing applications in a nice cli. DigitalOcean wraps up server management in a nice web UI and cli. It's a perfect match!
For implementation I want monorepos and monoliths and relational databases because that’s what I know best. I’m not saying this is better than other options, it’s just the best use of my skill.
So if you also want to run monoliths, take a look at dokku!
2. Getting a Dokku instance
Digital ocean has a cheap droplet that you can use. So checkout Digital Ocean, create a new “Dokku” droplet and follow their instructions for setting up how to login to your new droplet. You can get a droplet for free using a referral link.
You will need to use SSL to connect to the DigitalOcean droplet. For this you’ll have to use an existing certificate or create a new certificate and upload the public key to the server using Digital Ocean’s UI.
# generate a new certificate ssh-keygen -t ed25519 -C "email@example.com" # when asked for a name call it "digitaloceandokku" or similar # enter a pass phrase # add the cert to ssh agent ssh-add -K ~/.ssh/digitaloceandokku
Upload the public key to Digital Ocean.
Now add a
config file to the
~/.ssh directory if you don’t already have one. You will need to add an entry here to have macos use keychain to store your passphrase and to give yourself a shortcut for connecting to your new server!
Host dokku-as-darragh HostName 126.96.36.199 # replace with your IP User root IdentityFile ~/.ssh/digitaloceandokku # replace with your certificate AddKeysToAgent yes PreferredAuthentications publickey UseKeychain yes IdentitiesOnly yes
Now you should be able to connect to your Digital Ocean droplet easily
Done! you should see a prompt with a setup url to visit. Visit that and set up as you like. If you're having issues with ssh you can read my article about open ssl configuration here.
I recommend adding a domain name to the Dokku instance and letting it use virtual hosts. With this configuration you will get a new url for each app e.g.
Now you can start using
dokku commands. E.g.
Note on frozen terminals and ssh
When you open an ssh connection it takes over your input so regular exit and escape commands don’t work. If you don’t use the ssh session it will be closed on the Digital Ocean side but not on your side. It appears as if the terminal has “frozen”.
You can terminate ssh with
~. and that will drop you back to your terminal.
3. Create the application
We’re going to add an application called
house-lister to dokku.
dokku apps:create house-lister
4. Add a database service
If you haven’t used postgres on the instance yet, you must install the plugin
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
Now add a DB and link it to the new application
dokku postgres:create houselisterdatabase dokku postgres:link houselisterdatabase house-lister
5. Expose the database for debugging and testing (Optional)
Dokku uses internal networking so your database is protected from attackers. If you want to connect to it for debugging purposes temporarily then you can expose it to the internet using the following.
dokku postgres:expose houselisterdatabase 5432 # un-expose the DB when done! dokku postgres:unexpose houselisterdatabase
Be careful with that one. Leaving the database open all the time is unnecessary and risky.
5a. If you need Redis on Dokku
Use the same process as above but with the redis plugin
dokku redis:create houselisterredis dokku redis:link houselisterredis house-lister
Now your application will have a redis instance available at
REDIS_URL environment variable.
6. Add a domain to the application
You can add a domain name to make the application visible on the internet.
You'll have to add a DNS record that points to the IP address of the DigitalOcean droplet. You can add a wildcard to make it easy or you can add specific addresses.
You can read more about how DNS and domains work here.
The commands for assigning the domain on Dokku are
# list existing domains dokku domains:report house-lister # add domains dokku domains:add house-lister house-lister.mydomain.com # remove any default domain you don't need - dokku allows you to have multiple domains on the instance dokku domains:remove house-lister house-lister.anotherdomain.com
7. Add any configuration variables for your application
There may be some env vars you need to add for dokku plugins. See Let’s encrypt below for example.
Be careful with spaces in the dokku environment variable values. If you have a space in the value you will need to wrap the value in quotes.
dokku config:set house-lister APP_ENVIRONMENT_VAR_ONE=‘the value’ APP_ENVIRONMENT_VAR_TWO=‘the value’
You can avoid restarting the dokku application by using the
dokku config:set house-lister APP_ENVIRONMENT_VAR_ONE=‘the value’ APP_ENVIRONMENT_VAR_TWO=‘the value’ --no-restart
8. Add SSL to the application
This is optional but SSL is recommended these days and it’s free.
Dokku has a plugin for let’s encrypt. You have to install it if it’s not already there.
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
There are env vars you need to configure so let’s encrypt knows your email address. The plugin docs are worth reading: https://github.com/dokku/dokku-letsencrypt
Don’t forget to set up a cron to update your certs automatically every 30 days or so.
# Enable SSL for the application dokku letsencrypt:enable house-lister
9. Add the Dokku remote to your application
Dokku uses Git to deploy. You push your application to the dokku remote and that triggers a build.
Run this on your
local computer while in the code for your application to create the new remote.
Note that it’s not the root user this time
Note this is NOT run on the Digital Ocean droplet - run this on your local computer in the application repository.
git remote add dokku dokku@dokku-as-darragh:house-lister
10. Push your application to Dokku
Run this on your local machine
git push dokku master:master
of if you use main or any other branch name
git push dokku main:master
Done! You should see the application being deployed successfully.
A note on cert errors
If you get this error when setting up a cert you might have tried to add it before setting a domain for the application.
nginx: [emerg] cannot load certificate "/home/dokku/house-lister/tls/server.crt": BIO_new_file() failed (SSL: error:02001002:system library:fopen:No such file or directory:fopen('/home/dokku/house-lister/tls/server.crt','r') error:2006D080:BIO routines:BIO_new_file:no such file)
This scenario sets the application networking in a bad state. You can clean things up with the following commands
# clean up dokku proxy:ports-remove myapp 443 dokku domains:set myapp myapp.com.br www.myapp.com.br # now add the cert again dokku letsencrypt myapp
11. Maintaining your Dokku server
You'll have to maintain the droplet yourself. As often as you remember login and
apt update && apt upgrade.
You should also occasionally update your dokku instance.
sudo apt-get update dokku apps:list dokku ps:stop <app> # repeat to shut down each running app sudo apt-get install -qq -y dokku herokuish dokku ps:rebuild --all # restart all applications
Follow up dokku upgrades with plugin upgrades
dokku plugin:update postgres
Dokku makes it easy to run web apps for personal projects. The $5 per month is astounding value for what you get from Digital Ocean. You can get a droplet for free using a referral link.
Most of our personal projects have low enough usage that the droplet is plenty of power to run multiple apps.
Hit me up on Twitter if anything in the article isn’t working!