Introduction

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.

cmd

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.

cmd

git clone https://github.com/luckyframework/lucky_cli
cd lucky_cli
git checkout v0.28.0
    

Use the shards command to install the required Crystal shards.

cmd

shards install

# output 
Resolving dependencies
Fetching https://github.com/luckyframework/teeplate.git
Fetching https://github.com/luckyframework/lucky_task.git
Fetching https://github.com/crystal-ameba/ameba.git
Fetching https://github.com/crystal-community/future.cr.git
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.

cmd

crystal build src/lucky.cr
    

Move the Lucky binary to a location in your path.

cmd

sudo mv lucky /usr/local/bin/
    

Confirm the Lucky version that is installed.

cmd

lucky -v
  
# output
0.28.0
    

Clean up the Lucky source that was downloaded from Github.

cmd

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.

cmd

curl -O -L https://github.com/DarthSim/overmind/releases/download/v2.2.2/overmind-v2.2.2-linux-amd64.gz
    

Uncompress the gz file.

cmd

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

Add the executable bit to the Overmind binary.

cmd

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

Move the Overmind binary to a location in your path.

cmd

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

Verify the Overmind version installed.

cmd

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/database.cr 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.

cmd

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.

file

# ~/.zshrc
export DB_USERNAME="appuser"
export DB_PASSWORD="PASSWORD_FROM_PREVIOUS_STEP"
    

Source your rc file to load in the environment variables.

cmd

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.

cmd

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

API

 โ— 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/database.cr
  โ–ธ run script/setup
  โ–ธ run lucky dev to start the server
    

Change to the project directory.

cmd

cd testing123/
    

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

cmd

script/setup
  
# output
โ–ธ Running System Check
  โœ” Done

โ–ธ Installing node dependencies
  yarn install v1.22.11
  info No lockfile found.
  [1/4] Resolving packages...
warning browser-sync > socket.io > 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. (https://github.com/visionmedia/debug/issues/797)
warning browser-sync > socket.io > engine.io > 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. (https://github.com/visionmedia/debug/issues/797)
warning browser-sync > socket.io > socket.io-parser > 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. (https://github.com/visionmedia/debug/issues/797)
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 https://v8.dev/blog/math-random for details.
warning resolve-url-loader > rework > css > urix@0.1.0: Please see https://github.com/lydell/urix#deprecated
warning resolve-url-loader > rework > css > source-map-resolve > urix@0.1.0: Please see https://github.com/lydell/urix#deprecated
warning resolve-url-loader > rework > css > source-map-resolve > resolve-url@0.2.1: https://github.com/lydell/resolve-url#deprecated
  [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
  Fetching https://github.com/luckyframework/lucky.git
  Fetching https://github.com/luckyframework/authentic.git
  Fetching https://github.com/luckyframework/pulsar.git
  Fetching https://github.com/luckyframework/teeplate.git
  Fetching https://github.com/luckyframework/carbon.git
  Fetching https://github.com/luckyframework/carbon_sendgrid_adapter.git
  Fetching https://github.com/luckyframework/lucky_env.git
  Fetching https://github.com/luckyframework/lucky_task.git
  Fetching https://github.com/crystal-community/jwt.git
  Fetching https://github.com/luckyframework/lucky_flow.git
  Fetching https://github.com/luckyframework/habitat.git
  Fetching https://github.com/luckyframework/wordsmith.git
  Fetching https://github.com/luckyframework/avram.git
  Fetching https://github.com/luckyframework/shell-table.cr.git
  Fetching https://github.com/luckyframework/dexter.git
  Fetching https://github.com/will/crystal-pg.git
  Fetching https://github.com/matthewmcgarvey/webdrivers.cr.git
  Fetching https://github.com/luckyframework/lucky_router.git
  Fetching https://github.com/spider-gazelle/bindata.git
  Fetching https://github.com/spider-gazelle/openssl_ext.git
  Fetching https://github.com/crystal-community/future.cr.git
  Fetching https://github.com/crystal-loot/exception_page.git
  Fetching https://github.com/luckyframework/cry.git
  Fetching https://github.com/matthewmcgarvey/selenium.cr.git
  Fetching https://github.com/crystal-lang/crystal-db.git
  Fetching https://github.com/naqvis/crystar.git
  Fetching https://github.com/sija/backtracer.cr.git
  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.

cmd

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 http://127.0.0.1:5000
web          |
web          |
web          |    ๐ŸŽ‰ App running at http://127.0.0.1:3001
web          |
web          |
web          | [Browsersync] Proxying: http://127.0.0.1:5000
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 !

Summary

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.

Tags

lucky crystal