Lucky Logo

# Crystal Version

You will need Crystal installed for local development. Make sure to install all of Crystal’s dependencies for your system.

Lucky supports Crystal >= 1.10.0, <= 1.14.0

# 1. Install Crystal

Follow the Installing Crystal instructions page for your specific system.

# 2. Check installation

crystal -v

Should return between 1.10.0 and 1.14.0

# macOS (Apple Silicon) requirements

# 1. Install Homebrew

Installation instructions from the Homebrew website

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# macOS (Intel) requirements

# 1. Install Homebrew

Installation instructions from the Homebrew website

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install OpenSSL

brew install openssl

# 3. Configure SSL for Crystal

Add the following line to your shell configuration file. This will let Crystal know where to find OpenSSL.

You can run echo $SHELL in your terminal if you’re not sure whether you are using ZSH, Bash or Fish.

For ZSH (the default as of macOS Catalina):

macOS (Apple Silicon)

echo 'export PKG_CONFIG_PATH=/opt/homebrew/opt/openssl/lib/pkgconfig' >>~/.zshrc

macOS (Intel)

echo 'export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig' >>~/.zshrc

For Bash:

macOS (Apple Silicon)

echo 'export PKG_CONFIG_PATH=/opt/homebrew/opt/openssl/lib/pkgconfig' >>~/.bash_profile

macOS (Intel)

echo 'export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig' >>~/.bash_profile

For Fish:

macOS (Apple Silicon)

echo 'set -gx PKG_CONFIG_PATH /opt/homebrew/opt/openssl/lib/pkgconfig' >> ~/.config/fish/config.fish

macOS (Intel)

echo 'set -gx PKG_CONFIG_PATH /usr/local/opt/openssl/lib/pkgconfig' >> ~/.config/fish/config.fish

If you get an error like this: “Package libssl/libcrypto was not found in the pkg-config search path” then be sure to run this step so that Crystal knows where OpenSSL is located.

# Linux / WSL2 requirements

These are additional dependencies you will need in order to boot your Lucky application.

# Debian

apt-get install libc6-dev libevent-dev libpcre2-dev libpng-dev libssl-dev libyaml-dev zlib1g-dev

# Ubuntu

apt-get install libc6-dev libevent-dev libpcre2-dev libpcre3-dev libpng-dev libssl-dev libyaml-dev zlib1g-dev

# Fedora (28)

dnf install glibc-devel libevent-devel pcre2-devel openssl-devel libyaml-devel zlib-devel libpng-devel

# Windows requirements

Please see the requirements to install Crystal on Windows first.

# Install with Scoop

If you’re using Scoop on Windows, you can install the Lucky CLI using our Scoop package.

scoop bucket add lucky https://github.com/luckyframework/scoop-bucket
scoop install lucky

Windows compatibility is still experimental. Please report any issues you may have

# Install Lucky CLI with Homebrew

Once the required dependencies above are installed, set up Lucky for your system.

# 1. Install the Lucky CLI with Homebrew

brew install luckyframework/homebrew-lucky/lucky

# 3. Check installation

Let’s make sure the Lucky CLI installed correctly:

lucky -v

This should return 1.3.0

# Install Lucky CLI Manually

# 1. Clone the CLI repo

git clone https://github.com/luckyframework/lucky_cli

# 2. Change into the newly cloned directory

cd lucky_cli

# 3. Check out the latest released version

git checkout v1.3.0

# 4. Install shards

We call packages/libraries in Crystal “shards”. Let’s install the shards that Lucky CLI needs:

shards install --without-development

# 5. Build the CLI

shards build --production

# 6. Move the generated binary to your path

This will let you use lucky from the command line.

cp bin/lucky /usr/local/bin

Or anywhere else you deem fit

# 7. Check installation

Let’s make sure the Lucky CLI installed correctly:

lucky -v

This should return 1.3.0

# Postgres database (optional)

You can skip this if you don’t need database. Many sites (including this one) have no need for a database. In some cases, your data comes from a 3rd party API, or maybe you need a custom database engine other than PostgreSQL.

You can skip this if you plan to use Lucky with a Postgres docker container. Please note that a docker-compose configuration (with Postgres included) is provided out of the box when you start your project with lucky init.

# 1. Install Postgres

Lucky uses Postgres for its database. Install Postgres (macOS/Others)

# 1a. (macOS only) Ensure Postgres CLI tools installed

If you’re using Postgres.app on macOS make sure Postgres CLI tools are installed

sudo mkdir -p /etc/paths.d &&
  echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresapp

There are other installation methods available in Postgres CLI tools docs

# 1b. (Linux only) Configure PostgreSQL authentication trust for local development

Homebrew installed PostgreSQL on macOS are configured by default to allow password-less logins. But for Linux, if you wish to use PostgreSQL without a password, you’ll need to ensure your pg_hba.conf file is updated. We recommend adding this entry right after the postgres user entry:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust

Visit PostgreSQL Authentication Methods to learn more about available authentication methods and how to configure them for PostgreSQL.

Restart the postgresql service to activate the configuration changes.

sudo systemctl restart postgresql

# 2. Verify PostgreSQL CLI client (psql) is installed

First open a new session to reload your terminal, then:

psql --version

Should return psql (PostgreSQL) 10.x or higher.

# 3. Create a database user and set a password

You will need to create a database user with proper permissions to allow Lucky to manage the application database. There are several ways to accomplish this, but fortunatly PostgreSQL ships several command line tools to simplify this step. You will need to become the “postgres” user:

sudo su - postgres

Now create the user, and set the roles createrole, superuser, createdb then enter a password. In this example below, we will create a user named “lucky” and set a password of “lucky”.

createuser -dsrP lucky

Lucky versions 1.1.0 - 1.2.0 expects an existing database with the same name as the user you created in the previous step. The setup script and database tasks will fail after init if it does not exist. This requirement wil be removed in the next release.

createdb -O lucky lucky

Return back to your normal user.

exit

Now test the user can connect to the local postgres datbabase, enter the password for the user you just created when prompted.

psql -h localhost -U lucky -W postgres

If successful, you should see the following output, then type \q and hit enter to quit the client.

> psql -h localhost -U lucky -W postgres

Password:
psql (14.12 (Ubuntu 14.12-0ubuntu0.22.04.1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

postgres=# \q

# Node and Yarn (optional)

You can skip this if you only plan to build APIs.

# 1. Install

# 2. Check installation

node -v
yarn -v

Node should return greater than v11. Yarn should return greater than 1.x.

# Chrome Browser (optional)

You can skip this if you only plan to only build APIs.

Lucky uses Chromedriver for Testing HTML. The Chromedriver utility will be installed for you once you start running your tests; however, it requires the Chrome browser to be installed on your machine. If you don’t already have it installed, you can install it directly from Google.

You can also use an alternative chrome-like browser (e.g. Brave, Edge, etc…). See the Flow guides for customization options.

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