azu init

The azu init command initializes an existing directory as an Azu project. This is useful when you want to add Azu to an existing project or when you've cloned a project that doesn't have Azu configuration.

Overview

azu init [options]

Basic Usage

Initialize Current Directory

# Initialize the current directory as an Azu project
azu init

# Initialize with specific database
azu init --database postgres

# Initialize with specific project type
azu init --type api

Initialize Existing Project

# Navigate to existing project
cd my_existing_project

# Initialize as Azu project
azu init

# The command will:
# - Create Azu configuration files
# - Set up directory structure
# - Generate initial files
# - Install dependencies

Command Options

Option

Description

Default

--database <db>

Database type (postgres, mysql, sqlite)

postgres

--type <type>

Project type (web, api, cli)

web

--template <name>

Use specific template

default

--skip-git

Skip Git repository initialization

false

--skip-deps

Skip dependency installation

false

--force

Overwrite existing files

false

Use Cases

1. Adding Azu to Existing Crystal Project

# You have an existing Crystal project
cd my_crystal_app

# Initialize with Azu
azu init --database postgres

# This will:
# - Add Azu dependencies to shard.yml
# - Create Azu configuration files
# - Set up directory structure
# - Keep existing code intact

2. Converting Rails/Sinatra Project

# You have a Ruby project you want to convert
cd my_ruby_app

# Initialize as Azu project
azu init --type api --database postgres

# This creates the foundation for migration
# You can then gradually port your code

3. Setting Up Cloned Project

# Clone a project that doesn't have Azu setup
git clone https://github.com/user/project.git
cd project

# Initialize Azu
azu init

# Install dependencies
shards install

# Start development
azu serve

Generated Files

Configuration Files

azu.yml - Azu configuration:

name: my_app
version: 0.1.0
database: postgres
type: web

environments:
  development:
    database_url: postgres://localhost/my_app_development
    port: 3000
    debug: true

  test:
    database_url: postgres://localhost/my_app_test
    port: 3001
    debug: false

  production:
    database_url: <%= ENV["DATABASE_URL"] %>
    port: <%= ENV["PORT"] || 8080 %>
    debug: false

shard.yml - Updated with Azu dependencies:

name: my_app
version: 0.1.0

dependencies:
  azu:
    github: azutoolkit/azu
    version: ~> 1.0.0
  cql:
    github: azutoolkit/cql
    version: ~> 0.8.0

development_dependencies:
  ameba:
    github: crystal-ameba/ameba
    version: ~> 1.4.0

targets:
  my_app:
    main: src/my_app.cr

Directory Structure

my_app/
├── azu.yml                    # Azu configuration
├── shard.yml                  # Crystal dependencies
├── src/
│   ├── my_app.cr              # Main application
│   ├── server.cr              # HTTP server
│   ├── endpoints/             # HTTP endpoints
│   ├── models/                # Database models
│   ├── services/              # Business logic
│   ├── pages/                 # View components
│   ├── contracts/             # Request validation
│   ├── middleware/            # HTTP middleware
│   └── initializers/          # App configuration
├── public/
│   ├── assets/                # Static files
│   └── templates/             # HTML templates
├── spec/                      # Test files
├── db/                        # Database files
│   ├── migrations/            # Database migrations
│   └── seeds/                 # Seed data
└── config/                    # Configuration files
    └── environments/          # Environment configs

Core Application Files

src/my_app.cr - Main application:

require "azu"
require "./server"

module MyApp
  VERSION = "0.1.0"

  # Application configuration
  Azu.configure do |config|
    config.debug = true
    config.log_level = :debug
    config.host = "localhost"
    config.port = 3000
  end
end

src/server.cr - HTTP server:

require "azu"

# Load all application components
require "./endpoints/**"
require "./models/**"
require "./services/**"
require "./middleware/**"
require "./initializers/**"

# Start the server
Azu::Server.start

src/initializers/database.cr - Database setup:

require "cql"

CQL.setup do |config|
  config.database_url = ENV.fetch("DATABASE_URL", "postgres://localhost/my_app_development")
  config.log_level = :debug
end

Examples

Initialize Web Application

# Initialize as web application
azu init --type web --database postgres

# Output:
# 🚀 Initializing Azu project...
# 📁 Creating directory structure...
# ⚙️  Generating configuration files...
# 📦 Installing dependencies...
# ✅ Project initialized successfully!
#
# Next steps:
# 1. cd my_app
# 2. azu db:create
# 3. azu serve

Initialize API Application

# Initialize as API application
azu init --type api --database mysql

# This creates:
# - API-focused structure
# - JSON response handling
# - No HTML templates
# - API documentation setup

Initialize CLI Application

# Initialize as CLI application
azu init --type cli

# This creates:
# - CLI command structure
# - No web server
# - Command-line interface
# - Utility functions

Post-Initialization Steps

1. Install Dependencies

# Install Crystal dependencies
shards install

# Verify installation
crystal --version

2. Setup Database

# Create database
azu db:create

# Run migrations (if any)
azu db:migrate

# Seed data (if any)
azu db:seed

3. Start Development

# Start development server
azu serve

# Visit your application
# http://localhost:3000

4. Generate Your First Resource

# Generate a model
azu generate model user name:string email:string

# Generate endpoints
azu generate endpoint users

# Generate pages
azu generate page users/index

Migration from Other Frameworks

From Rails

# Initialize Azu project
azu init --type web --database postgres

# Migrate your models
# Convert ActiveRecord models to CQL models

# Migrate your controllers
# Convert Rails controllers to Azu endpoints

# Migrate your views
# Convert ERB templates to Azu pages

From Sinatra

# Initialize Azu project
azu init --type api --database postgres

# Migrate your routes
# Convert Sinatra routes to Azu endpoints

# Migrate your models
# Convert your data models to CQL models

From Express.js

# Initialize Azu project
azu init --type api --database postgres

# Migrate your routes
# Convert Express routes to Azu endpoints

# Migrate your middleware
# Convert Express middleware to Azu middleware

Troubleshooting

Permission Issues

# Check directory permissions
ls -la

# Fix permissions if needed
chmod 755 .

# Initialize in different location
azu init --path ~/projects/my_app

Existing Files Conflict

# Check for existing files
ls -la

# Use force to overwrite
azu init --force

# Or backup and initialize
cp -r . ../backup
azu init

Database Connection Issues

# Check database server
sudo systemctl status postgresql

# Create database user
sudo -u postgres createuser -s $USER

# Test connection
psql -h localhost -U $USER -d postgres

Dependency Issues

# Check Crystal installation
crystal --version

# Update Crystal
# (Follow Crystal installation guide)

# Clear shard cache
rm -rf lib/
shards install

Best Practices

1. Project Structure

# Use descriptive project names
azu init my_blog_app
azu init user_management_api
azu init data_processor_cli

# Avoid generic names
azu init app
azu init project
azu init test

2. Database Selection

# Development/Prototyping
azu init --database sqlite

# Web Applications
azu init --database postgres

# API Services
azu init --database postgres

# CLI Tools
azu init --database sqlite

3. Project Type

# Full-stack applications
azu init --type web

# API services
azu init --type api

# Command-line tools
azu init --type cli

4. Version Control

# Initialize Git repository
git init

# Add .gitignore
echo "lib/" >> .gitignore
echo "bin/" >> .gitignore
echo "*.log" >> .gitignore

# Initial commit
git add .
git commit -m "Initialize Azu project"

Integration with Existing Code

Preserving Existing Files

# Azu init preserves existing files
# Only creates missing structure

# Existing files are kept:
# - src/your_existing_code.cr
# - spec/your_existing_tests.cr
# - README.md
# - .gitignore

Gradual Migration

# 1. Initialize Azu
azu init

# 2. Move existing models
mv src/models/* src/models/

# 3. Convert endpoints gradually
# Start with one endpoint at a time

# 4. Update tests
# Convert existing tests to Azu format

The azu init command is perfect for adding Azu to existing projects or setting up projects that don't have Azu configuration.

Next Steps:

Project Structure - Understand the generated structure
Database Commands - Setup your database
Generate Command - Create your first components

Previousazu new Nextazu generate

Last updated 4 months ago