How to deploy a Crystal Lucky application with Dokku on Ubuntu 18.04

This tutorial will show how to set up an app written in the Crystal web framework Lucky with Dokku on Ubuntu 18.04.

You can run this setup on most low-end boxes, e.g. a $5 Digital Ocean droplet, or in my case, a $2.50 Hetzner Cloud Server.

By the end of the tutorial you'll know how to deploy your own Lucky apps and be able to manage them easily all on one server.

What is Lucky?

Lucky is a web framework written in Crystal. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.

What is Dokku?

Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku.


You'll need a Lucky app to deploy. If you don't have one then no problem! A fresh Lucky app comes with several goodies out of the box, a home page and an authentication system linked to a database. This is more than enough to work with. See Getting Started and Starting a Lucky Project. Make sure you have the project commited to git and ready for the first deployment.

Step 1 - Setting up the Dokku configuration

SSH into your server to get it ready for deployment.

ssh root@ip

In the following commands replace with your domain or subdomain. Replace exampledb with your preferred database name.

This will create the initial app container in Dokku, create the database, and link them both together. The last three lines set environment variables for the Lucky app. The first will tell Lucky to run the app in production mode, the second will tell Lucky what the app URL is, and the third will tell the app to run on port 5000 which Dokku will connect with Nginx to expose to the world.

dokku apps:create
dokku postgres:create exampledb
dokku postgres:link exampledb
dokku config:set LUCKY_ENV=production
dokku config:set
dokku config:set PORT=5000

There's a few more configuration details that need to be set. First, you'll need to tell Lucky the database details that are set in Dokku. Run the below command to get the database URL.

dokku postgres:info exampledb

Set the DATABASE_URL environment variable from the above output.

dokku config:set DATABASE_URL=postgres://...

Next, Lucky needs a secret key environment variable. In your app directory on your local machine run the following command which will generate a secure key.

lucky gen.secret_key

Then, back on your remote Dokku server add it to the SECRET_KEY_BASE environment variable.

dokku config:set SECRET_KEY_BASE=...

If you're planning to send emails through the app you'll also need to set SEND_GRID_KEY key, otherwise, change config/ to use in production (and make sure to commit!)

dokku config:set SEND_GRID_KEY=...

Your server is almost ready for deployment. If you're using a server with 2GB of RAM or less, you'll need to set up a Swap. Without it the deployment process will most likely run into memory issues. Checkout this tutorial for setting up a Swap. A 1G Swap should be more than enough.

Step 2 - Ready the app for deployment

Back in your local app add a new file called .buildpacks with the following contents

Step - 3 Deploy

Make a new commit. Finally you're ready to deploy. Run the following commands locally. The first will add your server as a remote origin for your git repo. The second will push the code to the server.

git remote add dokku
git push dokku master 

Step 4 - Set up SSL

Dokku lets you easily set up a Lets Encrypt SSL certificate. Run the following commands to do so

dokku config:set --no-restart
dokku letsencrypt

Spread the word

Share this article

Like this content?

Check out some of the apps that I've built!


Command-line snippet manager for power users



Third party app for iOS.



GUI for the rsync command