Installation

Get Azu up and running on your system with this comprehensive installation guide.

Prerequisites

Before installing Azu, ensure you have the following prerequisites:

Crystal Language

Azu requires Crystal 0.35.0 or higher. Install Crystal first:

macOS

# Using Homebrew (recommended)
brew install crystal-lang

# Verify installation
crystal version
# Should output: Crystal 1.x.x

Linux (Ubuntu/Debian)

# Add Crystal repository
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Install Crystal
sudo apt-get install crystal

# Verify installation
crystal version

Linux (CentOS/RHEL/Fedora)

# Add Crystal repository
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Install Crystal (Fedora)
sudo dnf install crystal

# Install Crystal (CentOS/RHEL)
sudo yum install crystal

# Verify installation
crystal version

Windows

# Using Chocolatey
choco install crystal

# Using Scoop
scoop install crystal

# Verify installation
crystal version

System Requirements

• Memory: Minimum 512MB RAM (2GB+ recommended)

• Storage: 100MB free space for Crystal + dependencies

• Network: Internet connection for downloading shards

Development Tools (Optional)

For the best development experience, install these tools:

# Git for version control
git --version

# A code editor (VS Code recommended)
code --version

# HTTP client for testing (curl, httpie, or Postman)
curl --version

Installing Azu

Method 1: New Project (Recommended)

Create a new Crystal project and add Azu as a dependency:

# Create a new Crystal application
crystal init app my-azu-app
cd my-azu-app

# Add Azu to dependencies

Edit your shard.yml:

name: my-azu-app
version: 0.1.0

authors:
  - Your Name <[e-mail]>

dependencies:
  azu:
    github: azutoolkit/azu
    version: ~> 0.5.26

crystal: >= 0.35.0

license: MIT

Install dependencies:

# Install Azu and its dependencies
shards install

# Verify installation
crystal run --help

Method 2: Add to Existing Project

If you have an existing Crystal project:

# Navigate to your project directory
cd your-existing-project

# Add Azu to shard.yml dependencies

Add to your shard.yml:

dependencies:
  azu:
    github: azutoolkit/azu
    version: ~> 0.5.26

Install:

shards install

Optional: Database Support with CQL

For database-backed applications, add CQL:

dependencies:
  azu:
    github: azutoolkit/azu
    version: ~> 0.5.28
  cql:
    github: azutoolkit/cql
    version: ~> 0.1.0

Add your database driver:

# PostgreSQL (recommended for production)
dependencies:
  pg:
    github: will/crystal-pg

# MySQL
dependencies:
  mysql:
    github: crystal-lang/crystal-mysql

# SQLite (development/testing)
dependencies:
  sqlite3:
    github: crystal-lang/crystal-sqlite3

See the Database documentation for complete setup instructions.

Method 3: Global Installation (Development)

For development and testing:

# Clone the repository
git clone https://github.com/azutoolkit/azu.git
cd azu

# Install dependencies
shards install

# Build the example application
crystal build --release playground/example_app.cr

# Run the example
./example_app

Verification

Verify your installation with a simple test:

1. Create a Test File

Create test_azu.cr:

require "azu"

# Simple test application
module TestApp
  include Azu

  configure do
    port = 4001  # Use different port to avoid conflicts
  end
end

# Basic endpoint
struct HelloEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Text)

  get "/"

  def call
    text "Hello, Azu is working!"
  end
end

# Start the application
TestApp.start [HelloEndpoint.new]

2. Run the Test

# Run the test application
crystal run test_azu.cr

You should see output like:

Server started at Mon 12/04/2023 10:30:45.
   ⤑  Environment: development
   ⤑  Host: 0.0.0.0
   ⤑  Port: 4001
   ⤑  Startup Time: 12.34 millis

3. Test the Endpoint

# Test the endpoint
curl http://localhost:4001/

# Expected output:
# Hello, Azu is working!

Troubleshooting Installation

Common Issues

Issue: "command not found: crystal"

Solution:

# Add Crystal to your PATH
export PATH="/usr/local/bin:$PATH"

# Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue: "shards: command not found"

Solution:

# Install shards separately if needed
crystal install shards

# Or install via package manager
# macOS: brew install crystal-lang
# Linux: Follow Crystal installation guide

Issue: "Error resolving dependencies"

Solution:

# Clear shard cache
rm -rf lib/
rm shard.lock

# Reinstall dependencies
shards install

Issue: "Permission denied" errors

Solution:

# Fix permissions
sudo chown -R $(whoami) /usr/local/bin
sudo chmod +x /usr/local/bin/crystal

# Or install with user permissions
crystal install --user

Version Compatibility

Check version compatibility:

# Check Crystal version
crystal version

# Check Azu version in shard.lock
cat shard.lock | grep azu

# Expected output shows compatible versions

Network Issues

If you're behind a corporate firewall or proxy:

# Set HTTP proxy if needed
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Or configure git to use proxy
git config --global http.proxy http://proxy.company.com:8080

Development Environment Setup

Recommended IDE Setup

VS Code

Install these extensions for the best Crystal development experience:

# Install Crystal extension
code --install-extension crystal-lang.crystal

# Install Crystal Tools extension
code --install-extension crystal-lang.crystal-tools

Vim/Neovim

# Install Crystal language server
crystal install language-server

# Add to your .vimrc or init.vim
# Plug 'crystal-lang-tools/vim-crystal'

Project Structure

After installation, your project should look like:

my-azu-app/
├── shard.yml          # Dependencies configuration
├── shard.lock         # Locked dependency versions
├── src/
│   └── my_azu_app.cr  # Main application file
├── lib/               # Installed dependencies
│   └── azu/          # Azu framework files
├── spec/              # Test files
└── .gitignore         # Git ignore rules

Environment Variables

Set up environment variables for different environments:

# Development
export AZU_ENV=development
export AZU_PORT=4000

# Production
export AZU_ENV=production
export AZU_PORT=8080
export AZU_HOST=0.0.0.0

Next Steps

After successful installation:

1. Your First Application → - Build your first Azu application

2. Configuration → - Configure your application

3. Core Concepts → - Learn Azu's fundamental concepts

Support

If you encounter issues during installation:

• Check the FAQ for common solutions

• Verify Crystal installation: crystal version

• Check network connectivity: ping github.com

• Review error messages for specific guidance

---

Installation complete! You're ready to start building with Azu.