The only requirement to use Azu is the Crystal Language itself
In order to build a full-featured Azu application, you will need a few dependencies installed.
the Crystal Programming Language - installation instruction can be found here
Shards command line tool for package management (Installed by default with Crystal installation)
a database - Azu recommends PostgreSQL but you can pick others or not use a database at all
Node.js for assets - which can be opt-out, especially if you are building APIs
Add the dependency to your shard.yml
:
Run shards install
Summary
At the end of this section, you must have installed Crystal, Shards, PostgreSQL and Node.js. Now that we have everything installed, let's define our first Azu application.
Learn how to get started with Azu and build applications
Let's get a Azu application up and running as quickly as possible.
We can run crystal init app my_app
from any directory in order to bootstrap our Azu application. Assuming that the name of our application is my_app
, let's run the following command:
shard.yml
Open your /my_app/shard.yml in your favorite editor and add the azu dependency
Azu is very light, flexible and module, for this reason it does not add front-end dependencies nor database dependencies. We will teach you how you can integrate those later in the guides
Now install Azu by running shards install
from the terminal
Now that you have install Azu, lets enable it in your project. Open /my_app/src/my_app.cr
With the simple include azu
you have unlocked the benefits of Azu for your project.
Before we begin, please take a minute to read the. By installing any necessary dependencies beforehand, we'll be able to get our application up and running smoothly.
When we use crystal init app my_app
to generates a new Azu application, it generated an empty Crystal App directory structure.
Many frameworks build a default directory structure to start with. Azu does not implement a default set of conventions, and instead provides you with patterns that fits best your needs.
Name |
MyApp.configure |
MyApp.log | This is the application logger and uses Crystal built in logger by default |
MyApp.env | Allows you to work with the application current environment Production, Development, Staging, etc. |
MyApp.config | Gets your application configuration for easy access from other parts of the code base |
MyApp.start | Starts the HTTP server |
Azu configuration properties are minimal this is to help you keep everything in a mental model without overloading your brain.
Azu configuration properties are minimal this is to help you keep everything in a mental model without overloading your brain.
Configuration properties lives within your application's main file.
Apps sometimes store config as constants in the code. This is a violation of the twelve-factor, which requires strict separation of config from code. Config varies substantially across deploys, code does not.
Azu follows the https://12factor.net/config standards this is why Azu first attempts to load configuration values from the environment first if not found then it loads from code.
We recommend for development use .env files.
.env
file
.env.local
file
.env.#{CRYSTAL_ENV}
file
.env.#{CRYSTAL_ENV}.local
file
Important: Azu does NOT load the .env
files automatically. It is up to you the developer to use your preferred method to load environment variables.
By default Azu ships with the following environments:
Build
Development
Test
Integration
Acceptance
Pipeline
Staging
Production
The current application environment is determined via the CRYSTAL_ENV variable.
Finally, you must know how to start the server.
Accepts a block and allows you to define Azu
Configuration
Environment Variables
Default Value
port
PORT
4000
jj port_reuse
PORT_REUSE
true
host
HOST
"0.0.0.0"
log
CRYSTAL_LOG_LEVEL, CRYSTAL_LOG_SOURCES
Log.for("Azu")
env
CRYSTAL_ENV
Environment::Development
template.path
TEMPLATES_PATH
"./templates"
template.error_path
ERROR_TEMPLATE
"./error_template"
ssl_cert
SSL_CERT
""
ssl_key
SSL_KEY
""
ssl_ca
SSL_MODE
""
ssl_mode
SSL_CA
"none"