Setting up a Kemal app is super simple, but if the app you're building is a little more than "super simple", there's a bit of things you'll end up doing each time you start a project. Why not have a mini generator that will do it for you?
This generator will generate a somewhat opinionated version of:
- Simple app with assets and views (customizable between ECR and Slang) setup
- Simple API with api versioning
- Simple app backed by a database (coming soon)
Since this is an application generator, there's no need to include it as a dependency, or shard. Just install it locally, and build the executable.
$ git clone firstname.lastname@example.org:jwoertink/fez.git $ cd fez/ $ make
You should now have a
bin/fez file to run. You can symlink this to a more global location like
/usr/local/bin to make it easier to use.
Optionally, you can use homebrew to install.
brew tap jwoertink/fez brew install fez
NOTE If you have issues running from homebrew, install from github, and report the error to homebrew-fez
Using fez is pretty easy. To see a help menu just run
fez -h. You can see the version of fez you're running with
Naming your app
To set the name of your application, you run fez with the name of the project. This is required in order to run.
This example will generate a
$ fez my_cool_app
Specifying the directory name
Fez gives you the option to create a different name for the directory your app is in than the actual app name. You can do this with the
-d flag. This flag is optional.
This example will generate an app called
my_cool_app in a
$ fez my_cool_app -d ~/Projects/myapp.cr or $ fez my_cool_app --directory=~/Projects/myapp.cr
If you don't specify a directory, fez will assume you want to use the current directory you're in.
Fez comes out of the box with several different templates:
- Kemal with slang
- Kemal with ECR
- Kemal as an API
- more coming later...
By default, fez uses Kemal with Slang as the default template. If you would like to switch back to using Crystal's built in ECR, or build an api, you will use the
-t flag. This flag is optional.
$ fez my_cool_app -t ecr or $ fez my_cool_app --template=ecr
Generating an API only application
$ fez my_api -t api
By default a JSON API will be generated with route versioning. You can read up on kave for more info about api customization.
Working with a fez generated app
Now that you've generated your shiny new Kemal app, it's time to start doing development on it. The generated app will contain a
README.md file that has all the instructions on how to start development.
Your app will have 2 primary dependencies to run.
If you have those two installed, then your next step is to
cd in to your new app's directory and run
$ cd ~/Projects Projects $ fez supertrain Projects $ cd supertrain Projects/supertrain $ make install
make install will install the shard dependencies for your app (like Kemal, duh!), and then install the ruby gem dependencies. You may be asking yourself why have ruby gem dependencies?... Ruby has tools that work great like
sass. Plus, chances are, you came to Crystal from Ruby anyway, and if you're on a Mac, Ruby is installed by default.
Ok, now that your app dependencies are installed, you have 2 options to boot this baby.
make run- This compiles your assets in to their natural form, and then boots kemal.
guard- This will boot your kemal and then watch for any changes to the files.
Both of these options will boot a server on
localhost:3001. The difference is that using guard allows you to do live-reloading.
If you need to use a console (REPL) for development, you can use the
make console command. You will have access to whatever has been required in your app's
Projects/supertrain $ make console => ok icr(0.19.1) > Kemal => Kemal icr(0.19.1) >
Now that you have a handle on developing your app, you will want to deploy it! There's a lot of different methods to deploying an app in to production, and fez takes the Capistrano appraoch.
- Edit your
config/deploy.rbfile with the necessary changes.
- Edit your
config/deploy/production.rbfile with more necessary changes
cap production deploy.
- Pray it all works!
If you'd like to help contribute, check out the Projects tab, or issues.
- Fork it ( https://github.com/jwoertink/fez/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request