Installing Lucky

# MacOS requirements

# 1. Install Homebrew

Installation instructions from the Homebrew website

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

# 2. Install OpenSSL

brew install openssl

# 3. Configure SSL for Crystal

You’ll need to tell Crystal how to find OpenSSL by adding an export to your ~/.bash_profile or ~/.zshrc.

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

For ZSH (the default as of macOS Catalina):

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

For Bash:

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

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 requirements

# 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

# Crystal Version

Lucky supports Crystal >= 1.0.0, <= 1.1.0

# 1. Install Crystal

Using asdf version manager:

We recommend using a version manager to make sure the correct version of Crystal is used with Lucky.

• Install asdf
• Install the asdf-crystal plugin:

asdf plugin-add crystal https://github.com/asdf-community/asdf-crystal.git

• Set up asdf so it uses the .crystal-version file to determine which version to use:

echo "legacy_version_file = yes" >>~/.asdfrc

• Install Crystal with asdf.

asdf install crystal 1.0.0

• See which version of crystal was installed

asdf list crystal

• Set global version of crystal to that version (1.0.0 is used as an example)

asdf global crystal 1.0.0

Or, install Crystal without a version manager

If you can’t get asdf installed or don’t want to use a version manager, you can install Crystal without a version manager.

# 2. Check installation

crystal -v

Should return at least 1.0.0

# Install Lucky CLI on macOS

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

# 1. Add the Lucky tap to Homebrew

brew tap luckyframework/homebrew-lucky

# 2. Install the Lucky CLI with Homebrew

brew install lucky

# 3. Check installation

Let’s make sure the Lucky CLI installed correctly:

lucky -v

This should return 0.28.0

# Install Lucky CLI on Linux

# 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 v0.28.0

# 4. Install shards

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

shards install

# 5. Build the CLI

crystal build src/lucky.cr

# 6. Move the generated binary to your path

This will let you use lucky from the command line.

mv lucky /usr/local/bin

# 7. Check installation

Let’s make sure the Lucky CLI installed correctly:

lucky -v

This should return 0.28.0

# Process manager

Lucky uses a process manager to watch assets and start the server in development.

Install one of these process managers: Overmind (recommended), Heroku CLI (great if you plan to use Heroku to deploy), forego, or foreman.

By default Lucky creates a Procfile.dev that defines what processes should be started when running lucky dev. You can modify the Procfile.dev to start other processes like running background jobs.

For WSL users on Windows, Overmind is not recommended due to compatibility issues.

# Postgres database

# 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) Password-less logins 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 more about available authentication methods and how to configure them for PostgreSQL.

Restart the postgresql service to activate the configuration changes.

# 2. Ensure Postgres CLI tools installed

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

psql --version

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

# Node and Yarn (optional)

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

# 1. Install

• Node. Requires at least v11
• Yarn

# 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.