azu serve

The azu serve command starts the development server with hot reloading capabilities. This is the primary command for development, automatically recompiling and restarting your application when files change.

Overview

azu serve [options]

Basic Usage

Start Development Server

# Start server on default port (4000)
azu serve

# Start on custom port
azu serve --port 4000

# Start with specific environment
azu serve --env development

Development with Hot Reloading

# Start server with file watching
azu serve

# Output:
# 🚀 Starting Azu development server...
# 📦 Compiling application...
# ✅ Compilation successful!
# 🌐 Server running at: http://localhost:4000
# 🔥 Hot reloading enabled
# 👀 Watching for file changes...
#
# Press Ctrl+C to stop the server

Command Options

Option	Description	Default
--port <port>	Server port	4000
--host <host>	Server host	localhost
--no-watch	Disable file watching	false
--verbose	Enable verbose output	false

Development Server Features

Hot Reloading

The development server automatically detects file changes and recompiles your application:

# Edit a file in src/
# The server automatically detects changes and recompiles

# Output when file changes:
# 👀 File changed: src/endpoints/users/index_endpoint.cr
# 📦 Recompiling...
# ✅ Recompilation successful!
# 🔄 Server restarted

Watched File Patterns:

• src/**/*.cr - Crystal source files

• config/**/*.cr - Configuration files

• public/templates/**/*.jinja - Jinja templates

• public/templates/**/*.html - HTML templates

• public/assets/**/*.css - CSS files

• public/assets/**/*.js - JavaScript files

Error Reporting

The server provides detailed error information during development:

# When compilation fails:
# ❌ Compilation failed!
#
# Error in src/models/user.cr:15:5
#   undefined method 'validates' for User
#
# Did you mean 'validate'?
#
# validates :email, presence: true
#     ^
#
# 💡 Fix the error and save to recompile

Environment Configuration

# Development environment (default)
azu serve --env development

# Production-like environment
azu serve --env staging

# Custom environment
azu serve --env custom

Server Configuration

Port and Host

# Default configuration
azu serve
# Server: http://localhost:4000

# Custom port
azu serve --port 8080
# Server: http://localhost:8080

# Bind to all interfaces
azu serve --host 0.0.0.0
# Server: http://0.0.0.0:4000

# Custom host and port
azu serve --host 192.168.1.100 --port 4000
# Server: http://192.168.1.100:4000

Verbose Mode

# Enable verbose output for detailed logging
azu serve --verbose

# Output includes:
# - File change notifications
# - Build process details
# - Debug information

File Watching

Automatic File Detection

The server watches for changes in:

src/
├── *.cr                    # Crystal source files
├── endpoints/              # Endpoint files
├── models/                 # Model files
├── services/               # Service files
├── middleware/             # Middleware files
└── initializers/           # Initializer files

public/
├── assets/                 # Static assets
├── templates/              # Template files
└── *.css, *.js, *.html     # Static files

Manual File Watching

# Watch specific directories
azu serve --watch src/,config/

# Disable file watching
azu serve --no-watch

# Watch with custom patterns
azu serve --watch "src/**/*.cr"

Performance Options

Worker Processes

# Single worker (default)
azu serve --workers 1

# Multiple workers for better performance
azu serve --workers 4

# Auto-detect CPU cores
azu serve --workers auto

Memory and CPU Limits

# Set memory limit
azu serve --memory-limit 512MB

# Set CPU limit
azu serve --cpu-limit 2

Environment-Specific Configuration

Development Environment

# config/environments/development.cr
Azu.configure do |config|
  config.debug = true
  config.log_level = :debug
  config.host = "localhost"
  config.port = 4000
  config.reload_templates = true
  config.cache_templates = false
end

Production Environment

# config/environments/production.cr
Azu.configure do |config|
  config.debug = false
  config.log_level = :info
  config.host = "0.0.0.0"
  config.port = ENV.fetch("PORT", "8080").to_i
  config.reload_templates = false
  config.cache_templates = true
end

Examples

Basic Development

# Start development server
azu serve

# Visit http://localhost:4000
# Make changes to files
# Server automatically recompiles and restarts

Custom Configuration

# Development with custom settings
azu serve --port 4000 --host 0.0.0.0 --debug

# Production-like testing
azu serve --env staging --port 8080

# SSL development
azu serve --ssl --port 443

Team Development

# Share server on network
azu serve --host 0.0.0.0 --port 4000

# Multiple developers can access:
# http://your-ip:4000

Mobile Development

# Access from mobile devices
azu serve --host 0.0.0.0 --port 4000

# Find your IP address
ifconfig | grep "inet " | grep -v 127.0.0.1

# Access from mobile: http://your-ip:4000

Troubleshooting

Port Already in Use

# Check what's using the port
lsof -i :4000

# Kill the process
kill -9 <PID>

# Or use a different port
azu serve --port 4000

Compilation Errors

# Check for syntax errors
crystal build src/main.cr

# Fix errors and save
# Server will automatically recompile

File Watching Issues

# Check file permissions
ls -la src/

# Restart server
# Press Ctrl+C and run again
azu serve

# Disable file watching temporarily
azu serve --no-watch

Memory Issues

# Increase memory limit
azu serve --memory-limit 1GB

# Check memory usage
ps aux | grep azu

# Restart server periodically
# Press Ctrl+C and run again

SSL Certificate Issues

# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Use custom certificate
azu serve --ssl --ssl-cert cert.pem --ssl-key key.pem

Best Practices

1. Development Workflow

# Start server
azu serve

# In another terminal, run tests
crystal spec --watch

# Make changes to files
# Server automatically recompiles
# Tests automatically run

2. Environment Management

# Use different environments
azu serve --env development  # Default
azu serve --env staging      # Pre-production
azu serve --env test         # Testing

3. Performance Optimization

# For large applications
azu serve --workers 4 --memory-limit 1GB

# For simple applications
azu serve --workers 1 --memory-limit 256MB

4. Security

# Don't bind to 0.0.0.0 in production
# Use reverse proxy (nginx, etc.)

# For development sharing
azu serve --host 0.0.0.0 --port 4000

5. Monitoring

# Enable debug mode for development
azu serve --debug

# Monitor logs
tail -f log/development.log

# Check server status
curl http://localhost:4000/health

Integration with Other Tools

VS Code Integration

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Azu Server",
      "type": "crystal",
      "request": "launch",
      "program": "${workspaceFolder}/src/main.cr",
      "args": ["serve", "--port", "4000"]
    }
  ]
}

Docker Development

# Dockerfile.dev
FROM crystallang/crystal:latest

WORKDIR /app
COPY . .

RUN shards install

EXPOSE 4000

CMD ["crystal", "run", "src/main.cr", "--", "serve", "--host", "0.0.0.0"]

# Run with Docker
docker build -f Dockerfile.dev -t my-app-dev .
docker run -p 4000:4000 -v $(pwd):/app my-app-dev

---

The azu serve command is essential for Azu development, providing a fast, reliable development server with hot reloading capabilities.

Next Steps:

• Development Workflows - Learn development patterns

• Database Commands - Manage your database

• Generate Command - Create new components