# Deploy Command Usage Guide
Quick reference for the `au deploy` command and all its options.
---
## Basic Usage
```bash
# Deploy with default settings (reads from gold files)
au deploy
# Explicit start command (same as above)
au deploy start
```
---
## CLI Flags
### Override Port
```bash
# Deploy on a different port
au deploy --port 3000
```
### Environment Variables
```bash
# Add single environment variable
au deploy -e DATABASE_URL=sqlite://data.db
# Add multiple environment variables
au deploy \
-e DATABASE_URL=sqlite://data.db \
-e LOG_LEVEL=debug \
-e RUST_LOG=info
```
### Volume Mappings
```bash
# Mount single volume
au deploy -v ./data:/app/data
# Mount multiple volumes
au deploy \
-v ./data:/app/data \
-v ./logs:/app/logs \
-v ./config:/app/config
```
### Force Rebuild
```bash
# Force rebuild without cache (Docker)
au deploy --force-rebuild
```
### Docker Compose
```bash
# Use docker-compose instead of direct Docker API
au deploy --compose
# Compose with custom settings
au deploy --compose \
--port 3000 \
-e DATABASE_URL=postgres://localhost/db \
-v ./data:/app/data
```
### Deployment Target
```bash
# Deploy to Docker (default)
au deploy --target docker
# Deploy to systemd (Linux only - TODO)
au deploy --target systemd
# Deploy as daemon (TODO)
au deploy --target daemon
# Deploy as local process (TODO)
au deploy --target local
```
---
## Combined Examples
### Full Production Deployment
```bash
au deploy \
--port 8080 \
-e DATABASE_URL=postgres://prod-db/myapp \
-e LOG_LEVEL=info \
-e RUST_LOG=warn \
-v ./data:/app/data \
-v ./logs:/app/logs \
--force-rebuild
```
### Development with Docker Compose
```bash
au deploy --compose \
--port 3000 \
-e LOG_LEVEL=debug \
-e RUST_LOG=debug \
-v ./data:/app/data
```
### Quick Test Deploy
```bash
# Just override port, use everything else from gold files
au deploy --port 9000
```
---
## Management Commands
### Check Status
```bash
au deploy status
```
### View Logs
```bash
# View last 100 lines
au deploy logs
# Follow logs (TODO)
au deploy logs --follow
# Show last N lines (TODO)
au deploy logs --tail 50
```
### Restart
```bash
au deploy restart
```
### Stop
```bash
au deploy stop
```
---
## Configuration Priority
Settings are applied in this order (later overrides earlier):
1. **Default values** (port 8080, Docker target, etc.)
2. **Gold file config** (`config deployment { ... }` block)
3. **CLI flags** (highest priority)
### Example
Gold file:
```au
config deployment {
port = 3000
environment {
LOG_LEVEL = "info"
}
}
```
Command:
```bash
au deploy --port 8080 -e LOG_LEVEL=debug -e DATABASE_URL=sqlite://db.db
```
Result:
- Port: **8080** (from CLI flag)
- LOG_LEVEL: **debug** (from CLI flag)
- DATABASE_URL: **sqlite://db.db** (from CLI flag)
---
## Real-World Examples
### Blog Application
```bash
au deploy \
--port 80 \
-e DATABASE_URL=postgres://localhost/blog \
-e ADMIN_EMAIL=admin@example.com \
-e JWT_SECRET=your-secret-key \
-v ./uploads:/app/uploads \
-v ./data:/app/data
```
### API Server
```bash
au deploy \
--port 8080 \
-e API_KEY=your-api-key \
-e CORS_ORIGINS=https://example.com \
-e RATE_LIMIT=1000 \
--force-rebuild
```
### Microservice with Compose
```bash
au deploy --compose \
--port 5000 \
-e SERVICE_NAME=user-service \
-e REDIS_URL=redis://redis:6379 \
-e DATABASE_URL=postgres://db:5432/users
```
---
## Troubleshooting
### Deploy Fails on Validation
```bash
# Check what's wrong with gold files
au check
# Fix errors, then deploy
au deploy
```
### Port Already in Use
```bash
# Use a different port
au deploy --port 8081
```
### Need Fresh Build
```bash
# Force rebuild from scratch
au deploy --force-rebuild
```
### Docker Not Running
```
Error: Failed to connect to Docker daemon. Is Docker running?
```
Solution: Start Docker Desktop or Docker daemon.
### Permission Denied on Volumes
Make sure host directories exist and have correct permissions:
```bash
mkdir -p ./data ./logs
chmod 755 ./data ./logs
au deploy -v ./data:/app/data -v ./logs:/app/logs
```
---
## Tips & Best Practices
### Use Gold Files for Stable Config
Put your production config in gold files:
```au
config deployment {
target = "docker"
port = 8080
restart = "unless-stopped"
environment {
DATABASE_URL = "${DATABASE_URL}" // From env
LOG_LEVEL = "info"
}
volumes {
"./data" = "/app/data"
}
healthcheck {
endpoint = "/health"
interval = "30s"
timeout = "10s"
retries = 3
}
}
```
Then deploy with just:
```bash
au deploy
```
### Use CLI Flags for Overrides
Use flags for temporary changes or environment-specific overrides:
```bash
# Development
au deploy --port 3000 -e LOG_LEVEL=debug
# Staging
au deploy --port 8080 -e LOG_LEVEL=info
# Production
au deploy --port 80 -e LOG_LEVEL=warn --force-rebuild
```
### Volume Persistence
Always mount data directories as volumes to persist across deployments:
```bash
au deploy \
-v ./data:/app/data \
-v ./logs:/app/logs
```
### Health Checks
Configure health checks in gold files for production:
```au
config deployment {
healthcheck {
endpoint = "/api/health"
interval = "30s"
timeout = "10s"
retries = 5
}
}
```
### Environment Variables from .env
```bash
# Load from .env file (shell feature)
```
Or reference in gold files:
```au
config deployment {
environment {
DATABASE_URL = "${DATABASE_URL}" // Will use shell env var
}
}
```
---
## See Also
- [DEPLOY_STATUS.md](DEPLOY_STATUS.md) - Implementation status and internals
- [Gold File Syntax](../../docs/GOLD_FILE_SYNTAX_OPTIONS.md) - Full config syntax
- [Example Config](../../examples/deployment-config/gold/app.au) - Complete example
---
**Quick Reference Card:**
```bash
au deploy # Deploy with defaults
au deploy --port 3000 # Custom port
au deploy -e KEY=value # Add env var
au deploy -v ./data:/app/data # Add volume
au deploy --force-rebuild # Rebuild from scratch
au deploy --compose # Use docker-compose
au deploy status # Check status
au deploy logs # View logs
au deploy restart # Restart
au deploy stop # Stop
```