I am a big fan of the web framework Ruby on Rails. Recently, I have been looking into the Crystal programming language and was excited to find out there are a couple of options for web frameworks similar in philosophy to Rails. One of those options is Lucky.

"Lucky is a web framework written in Crystal. It helps you work quickly, catch bugs at compile time, and deliver blazing fast responses."

In this post I will show you how to install and start a project with the Lucky web framework.

Software Used

The following software versions are used in this post.

  • Ubuntu - 20.04 Server
  • Crystal - 1.1.1
  • Lucky - 0.28.0
  • Overmind - 2.2.2
  • PostgreSQL - 13.4
  • Node JS - v16.7.0
  • Yarn - 1.22.11

Pre-flight Check

This post assumes that Crystal, Postgres and Node JS + Yarn are already installed. Check the below posts for instructions for Ubuntu 2004.

Install Lucky

Install the dependencies.


sudo apt-get install -y libc6-dev libevent-dev libpcre2-dev libpcre3-dev libpng-dev libssl-dev libyaml-dev zlib1g-dev build-essential tmux

Grab the Lucky source code.


git clone
cd lucky_cli
git checkout v0.28.0

Use the shards command to install the required Crystal shards.


shards install

# output 
Resolving dependencies
Using future (1.0.0)
Using teeplate (0.8.4)
Using lucky_task (0.1.0)
Installing ameba (0.14.3)
Postinstall of ameba: make bin && make run_file
Writing shard.lock

Build the Lucky CLI binary.


crystal build src/

Move the Lucky binary to a location in your path.


sudo mv lucky /usr/local/bin/

Confirm the Lucky version that is installed.


lucky -v
# output

Clean up the Lucky source that was downloaded from Github.


cd ..
rm -rf lucky_cli/

Install Overmind

Lucky uses a process manager to watch assets and start the development server. I am using Overmind, as its recommeded by the Lucky project.

Download the Overmind binary gz file.


curl -O -L

Uncompress the gz file.


gunzip overmind-v2.2.2-linux-amd64.gz

Add the executable bit to the Overmind binary.


chmod +x overmind-v2.2.2-linux-amd64

Move the Overmind binary to a location in your path.


sudo mv overmind-v2.2.2-linux-amd64 /usr/local/bin/overmind

Verify the Overmind version installed.


overmind -v

# output
Overmind version 2.2.2

Database User

Before we go any further, lets get the Postgres Database user setup. I am using the default user that is found in the config/ configuration file of a Lucky project. If you want to use a different user, then the details of the user will need to be updated in that file.

Create the application DB user.


sudo -u postgres createuser -s appuser -P

# output
Enter password for new role:
Enter it again:

Set environment variables for the DB user in your environment file. I am using ZSH for my shell so mine is in ~/.zshrc. Use your prefered text editor to add the environment variables.


# ~/.zshrc
export DB_USERNAME="appuser"

Source your rc file to load in the environment variables.


source ~/.zshrc

Start a Lucky Project

The next step is to initialize the Lucky project. I will be creating a project named testing123 that has full HTML support (not just an API) and with authentication. The lucky init command, has a handy interactive mode.


lucky init
# output
Welcome to Lucky v0.28.0 ๐ŸŽ‰

Project name?: testing123

Lucky can generate different types of projects

Full (recommended for most apps)

 โ— Great for server rendered HTML or Single Page Applications
 โ— Webpack included
 โ— Setup to compile CSS and JavaScript
 โ— Support for rendering HTML


 โ— Specialized for use with just APIs
 โ— No webpack
 โ— No static file serving or public folder
 โ— No HTML rendering folders

API only or full support for HTML and Webpack? (api/full): full

Lucky can be generated with email and password authentication

  โ— Sign in and sign up
  โ— Mixins for requiring sign in
  โ— Password reset
  โ— Token authentication for API endpoints
  โ— Generated files can easily be removed/customized later

Generate authentication? (y/n): y


Done generating your Lucky project

  โ–ธ cd into testing123
  โ–ธ check database settings in config/
  โ–ธ run script/setup
  โ–ธ run lucky dev to start the server

Change to the project directory.


cd testing123/

Kick off the setup script to install all the required dependencies.


# output
โ–ธ Running System Check
  โœ” Done

โ–ธ Installing node dependencies
  yarn install v1.22.11
  info No lockfile found.
  [1/4] Resolving packages...
warning browser-sync > > debug@4.1.1: Debug versions >=3.2.0 <3.2.7 || >=4 <4.3.1 have a low-severity ReDos regression when used in a Node.js environment. It is recommended you upgrade to 3.2.7 or 4.3.1. (
warning browser-sync > > > debug@4.1.1: Debug versions >=3.2.0 <3.2.7 || >=4 <4.3.1 have a low-severity ReDos regression when used in a Node.js environment. It is recommended you upgrade to 3.2.7 or 4.3.1. (
warning browser-sync > > > debug@4.1.1: Debug versions >=3.2.0 <3.2.7 || >=4 <4.3.1 have a low-severity ReDos regression when used in a Node.js environment. It is recommended you upgrade to 3.2.7 or 4.3.1. (
warning laravel-mix > node-libs-browser > url > querystring@0.2.0: The querystring API is considered Legacy. new code should use the URLSearchParams API instead.
warning laravel-mix > webpack-dev-server > sockjs > uuid@3.4.0: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See for details.
warning resolve-url-loader > rework > css > urix@0.1.0: Please see
warning resolve-url-loader > rework > css > source-map-resolve > urix@0.1.0: Please see
warning resolve-url-loader > rework > css > source-map-resolve > resolve-url@0.2.1:
  [2/4] Fetching packages...
  info fsevents@2.3.2: The platform "linux" is incompatible with this module.
  info "fsevents@2.3.2" is an optional dependency and failed compatibility check. Excluding it from installation.
  [3/4] Linking dependencies...
warning " > compression-webpack-plugin@7.1.2" has unmet peer dependency "webpack@^5.1.0".
warning " > sass-loader@10.2.0" has unmet peer dependency "webpack@^4.36.0 || ^5.0.0".
  [4/4] Building fresh packages...
  success Saved lockfile.
  Done in 25.45s.

โ–ธ Compiling assets
  yarn run v1.22.11
  $ mix
  โ„น Compiling Mix

  Laravel Mix v6.0.28

  โœ” Compiled Successfully in 765ms
  โ”‚                              File โ”‚ Size     โ”‚
  โ”‚                        /js/app.js โ”‚ 73.6 KiB โ”‚
  โ”‚                       css/app.css โ”‚ 5.37 KiB โ”‚
  โœ” Mix: Compiled successfully in 814.75ms
  Done in 2.24s.
  โœ” Done

โ–ธ Installing shards
  Resolving dependencies
  Installing lucky_task (0.1.0)
  Installing habitat (0.4.7)
  Installing wordsmith (0.3.0)
  Installing db (0.10.1)
  Installing pg (0.24.0)
  Installing dexter (0.3.3)
  Installing shell-table (0.9.3 at fefbc8b)
  Installing pulsar (0.2.2)
  Installing avram (0.21.1)
  Postinstall of avram: script/precompile_tasks
  Installing lucky_router (0.5.0)
  Installing cry (0.4.3)
  Installing backtracer (1.2.1)
  Installing exception_page (0.2.0)
  Installing future (1.0.0)
  Installing teeplate (0.8.4)
  Installing lucky (0.28.0)
  Postinstall of lucky: script/precompile_tasks
  Installing authentic (0.8.0)
  Installing carbon (0.2.0)
  Installing carbon_sendgrid_adapter (0.1.0)
  Installing lucky_env (0.1.3)
  Installing openssl_ext (2.1.5)
  Installing bindata (1.9.1)
  Installing jwt (1.5.1)
  Installing selenium (0.9.1)
  Installing crystar (0.2.0)
  Installing webdrivers (0.4.0)
  Installing lucky_flow (0.7.3)
  Writing shard.lock

โ–ธ Creating the database
  Done creating testing123_development

โ–ธ Verifying postgres connection
  โœ” Connection verified

โ–ธ Migrating the database
  Migrated CreateUsers::V00000000000001

โ–ธ Seeding the database with required and sample records
  Done adding required data
  Done adding sample data
  โœ” Done

โ–ธ Run 'lucky dev' to start the app

Now start the dev server.


lucky dev
# output
system       | Tmux socket name: overmind-testing123-mgz0NPa-7OEepBqCCxXzFx
system       | Tmux session ID: testing123
system       | Listening at ./.overmind.sock
system_check | Started with pid 88551...
assets       | Started with pid 88557...
web          | Started with pid 88553...
web          | Beginning to watch your project
web          | Compiling...
yarn run v1.22.11
$ mix watch

assets       | โœ” Mix
assets       |   Compiled successfully in 827.15ms
assets       |
assets       |
assets       |
assets       |    Laravel Mix v6.0.28
assets       |
assets       |
assets       | โœ” Compiled Successfully in 772ms
assets       | โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
assets       | โ”‚                                                              File โ”‚ Size     โ”‚
assets       | โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
assets       | โ”‚                                                        /js/app.js โ”‚ 73.6 KiB โ”‚
assets       | โ”‚                                                       css/app.css โ”‚ 5.37 KiB โ”‚
assets       | โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
web          | Done compiling
yarn run v1.22.11
$ /home/bradmin/code/crystal/lucky/testing123/node_modules/.bin/browser-sync start -c bs-config.js --port 3001 -p
web          |
web          |
web          |    ๐ŸŽ‰ App running at
web          |
web          |
web          | [Browsersync] Proxying:
web          | [Browsersync] Access URLs:
web          |  ----------------------------
web          |  Local: http://localhost:3001
web          |  ----------------------------
web          | [Browsersync] Watching files...
web          |
web          | GET /
web          |  โ–ธ Handled by Home::Index
web          |  โ–ธ Rendered Lucky::WelcomePage
web          |  โ–ธ Sent 200 OK (522.84ยตs)

Access Web Application

If all is well, you can access your shiny new Lucky application at http://<server-ip>:30001 !


In this post, we setup an Ubuntu 2004 server with PostgreSQL to run a Crystal based Lucky web application. Look at you, you are a champion.


lucky crystal