Lucky Web Framework Getting Started

updated: 24th of August 2021

published: 20th of August 2021

Intro

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 !

Outro

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.

https://luckyframework.org/

https://luckyframework.org/guides/getting-started/installing

https://github.com/luckyframework/lucky

https://github.com/DarthSim/overmind