Lucky Logo

# Quickstart

If you are comfortable with Heroku, here are the (brief) steps you need to get up and running:

If not already created, create an app:

heroku create <APP_NAME>

Optional: if you created the app through the dashboard instead of the CLI, add a git remote that points to your Heroku app:

heroku git:remote -a <APP-NAME>

Add the following buildpacks in order:

# Skip this buildpack for API only app. Add this for HTML and Assets
heroku buildpacks:add heroku/nodejs

# Then add this for all Lucky apps
heroku buildpacks:add lucky-framework/lucky

Set LUCKY_ENV to production:

heroku config:set LUCKY_ENV=production


heroku config:set SECRET_KEY_BASE=$(lucky gen.secret_key)


heroku config:set APP_DOMAIN=

If you don’t have a custom domain set this to https://<APP_NAME>


heroku config:set SEND_GRID_KEY=<key from>

If you’re not sending emails, set the key to unused or go to config/ and change the adapter to Carbon::DevAdapter.

Add a postgresql database add-on:

heroku addons:create heroku-postgresql:hobby-dev

Push to Heroku:

git push heroku main

Each step is explained in more detail below.

# Getting started

For those new to the Heroku platform, or those that want more guidance, we’ll walk through the process step-by-step.

First, we’ll need to create an account at Heroku. Once that’s done, create a new app via the Heroku Dashboard. We can give the app a unique name or leave it blank and Heroku will create one for us. For this tutorial, we’ll use the placeholder <APP-NAME>.

# Setting up git for Heroku

The Heroku CLI will let us manage our app from the command line. A normal installation of Lucky requires that it’s installed, so we should already have the heroku command. The first thing we’ll do is to connect our Lucky app to the Heroku app by adding a git remote:

heroku git:remote -a <APP-NAME>

# Buildpacks

Most Lucky apps are built with both Crystal and Node.js. Heroku uses buildpacks to compile each executable portion of an app. The Node.js buildpack must go first so that Heroku can compile the app’s assets before Lucky is compiled. To enable a Node.js app on Heroku, we’ll add the official Node.js buildpack to our app:

heroku buildpacks:add heroku/nodejs

While Heroku has a buildpack for Node.js apps, it doesn’t have one for Crystal apps (yet). Fortunately for us, Lucky has such a buildpack! We’ll add it so Heroku can download and install the dependencies for Lucky:

heroku buildpacks:add lucky-framework/lucky

# Adding environment variables


Lucky needs a couple of environment variables to operate as a production app. The first is the LUCKY_ENV. We’ll set it to production. This will signal to Lucky that it should, for example, display absolute timestamps in the server log, and use additional environment variables for its configuration:

heroku config:set LUCKY_ENV=production


Lucky needs the app’s domain when it builds full URLs.

heroku config:set APP_DOMAIN=


Next, we’ll generate a secret key for our app. Among other things, this key will give us a unique value for our site’s cookies. Once we have our secret key, we can set the SECRET_KEY_BASE environment variable with that key:

heroku config:set SECRET_KEY_BASE=$(lucky gen.secret_key)

# SEND_GRID_KEY (set to “unused” if not sending emails)

If you are sending emails, you’ll need to sign up for an account and get an API key from Once you have it we can set the SECRET_KEY_BASE environment variable:

heroku config:set SEND_GRID_KEY=<KEY>

If you don’t need to send emails you can set the value to unused.

Alternatively, you can change the config in config/ to use the Carbon::DevAdapter. When you open the file there will be comments showing you how to do this.

Read more about emailing with Carbon

# Adding a database

Heroku offers a free database add-on with up to 10,000 rows. This is almost certainly enough for most hobby projects, at least to get started. If we need more rows or resources, they offer upgraded plans. For this tutorial, we’re going to stick with the hobby-dev plan.

We’ll attach the database add-on to our app:

heroku addons:create heroku-postgresql:hobby-dev

# Uploading the app

The last step is to upload our app’s code up to Heroku. We’ll do this with the standard git push command and copy our local main branch to Heroku’s main branch:

git push heroku main

First, the source code will be uploaded to Heroku. Heroku will detect the Node.js and Crystal components of the app, download the appropriate dependencies, and compile everything together. These steps may take a few minutes to run. Finally, it will start Lucky and run the app!

Migrations will happen automatically when the app is pushed to Heroku. Lucky makes it so you never have to worry about forgetting to migrate our app when it’s deployed! Read more about the release phase.

To see our deployed app, use Heroku’s open command:

heroku open

Happy shipping! 🚀

# Running tasks

To run any of your Lucky tasks on your new Heroku container, use Heroku’s run command:

heroku run lucky db.create_required_seeds

For a list of the tasks available, run lucky -h locally.

See a problem? Have an idea for improvement? Edit this page on GitHub