---
description: Rails Deployment with Kamal
applyTo: "config/deploy.yml"
---

# Rails Deployment with Kamal

## Core Philosophy

- Deploy containerized Rails applications without complexity
- Use Kamal for zero-downtime deployments
- Keep deployment configuration simple and version controlled
- Leverage Docker without becoming a Docker expert
- Deploy anywhere with SSH access

## Kamal Principles

- One command deployments with automatic rollback
- Built-in health checks and rolling updates
- Integrated secret management
- No Kubernetes complexity needed
- Direct SSH-based deployment to servers

## Configuration Strategy

- Keep all deployment config in `config/deploy.yml`
- Use environment-specific settings wisely
- Store secrets securely with Kamal's encryption
- Version control deployment configuration
- Document server requirements clearly

## Server Prerequisites

- Ensure servers have Docker installed
- Configure SSH access for deployment user
- Set up firewall rules appropriately
- Prepare SSL certificates if needed
- Verify sufficient disk space and memory

## Environment Management

- Use Kamal's built-in environment variable handling
- Separate secrets from non-sensitive configuration
- Use `.env` files for local development only
- Leverage Rails credentials for application secrets
- Keep production passwords out of version control

## Container Strategy

- Build minimal production Docker images
- Use multi-stage builds to reduce size
- Install only production dependencies
- Configure proper health check endpoints
- Set appropriate resource limits

## Database Configuration

- Use managed databases when possible
- Configure connection pooling appropriately
- Set up automated backups
- Use read replicas for scaling
- Handle database migrations carefully

## Asset Management

- Precompile assets during Docker build
- Use CDN for asset delivery
- Configure proper cache headers
- Compress assets appropriately
- Handle asset versioning correctly

## Health Checks

- Implement `/up` endpoint for health monitoring
- Check database connectivity
- Verify background job processing
- Monitor external service dependencies
- Return appropriate status codes

## Deployment Workflow

- Run tests before deployment
- Build Docker image with correct tags
- Push to container registry
- Deploy with health check verification
- Monitor deployment progress

## Zero-Downtime Deployments

- Use Kamal's rolling deployment strategy
- Ensure backwards-compatible migrations
- Handle long-running requests gracefully
- Implement proper connection draining
- Test rollback procedures

## SSL and Security

- Use Let's Encrypt for SSL certificates
- Configure Traefik for SSL termination
- Implement proper security headers
- Keep containers updated
- Monitor for security vulnerabilities

## Logging and Monitoring

- Centralize application logs
- Use structured logging format
- Monitor application performance
- Set up error tracking
- Configure alerting rules

## Background Jobs

- Deploy workers alongside web servers
- Configure appropriate concurrency
- Monitor job queue depth
- Handle worker restarts gracefully
- Separate critical from bulk job workers

## Scaling Strategy

- Start with vertical scaling
- Add horizontal scaling when needed
- Use load balancer health checks
- Monitor resource utilization
- Plan capacity ahead of demand

## Backup and Recovery

- Automate database backups
- Test restore procedures regularly
- Back up uploaded files
- Document recovery procedures
- Store backups in multiple locations

## Performance Optimization

- Use HTTP/2 where possible
- Enable gzip compression
- Configure appropriate timeouts
- Monitor response times
- Optimize container startup time

## Troubleshooting

- Use Kamal's built-in debugging commands
- Access container logs easily
- Connect to running containers
- Monitor deployment events
- Keep rollback procedures ready

## Maintenance

- Schedule maintenance windows
- Communicate with users appropriately
- Test updates in staging first
- Monitor after deployments
- Document common issues

## Cost Optimization

- Right-size server resources
- Use spot instances where appropriate
- Monitor resource utilization
- Clean up unused resources
- Optimize container image sizes

## Disaster Recovery

- Document recovery procedures
- Test disaster scenarios
- Maintain off-site backups
- Have communication plan ready
- Know your RTO and RPO

## Best Practices

- Deploy frequently in small batches
- Automate everything possible
- Monitor before, during, and after deploys
- Keep deployment simple and boring
- Document non-obvious decisions

## Common Patterns

- Blue-green deployments for critical updates
- Canary deployments for gradual rollouts
- Feature flags for controlled releases
- Database migrations as separate step
- Scheduled deployments for low-traffic periods

## Security Considerations

- Rotate credentials regularly
- Use IAM roles where possible
- Audit server access
- Keep containers minimal
- Scan images for vulnerabilities

Remember: Kamal makes deployment as simple as `kamal deploy`. Focus on your application, not deployment complexity.