Debug Failed Deployments

When a deployment fails, don’t panic! Here’s how to systematically debug and fix the issue.

Quick Diagnosis

1. SSH into your server where the deployment occurred
2. Check container status with docker compose ls
3. Identify the failing service (usually shows “restarting” status)
4. Navigate to the app directory and investigate

Step-by-Step Debugging

1. Check Container Status

ssh root@your-server-ip
docker compose ls

Look for services with “restarting” status - these are your problem containers.

Note: You can find the ssh command on the Blossom server show page.

2. Navigate to Failing Service

cd /blossom/apps/app-111/app-111-web-swap
docker compose ps

Note: Blossom performs a zero-downtime swap deployment if you’ve configured Health Checks. If the deployment is failing, check the swap deployment. There should be clues from looking at the logs there. This gives you the opportunity to fix the issue before deploying bad code.

3. Check Logs (Unstable Containers)

When containers are constantly restarting, logs are your best friend:

docker compose logs -n 100

This shows the last 100 lines of logs. Look for:

• NameError: Missing constants/modules
• LoadError: Missing files or gems
• Database connection errors
• Environment variable issues

4. Debug Inside Container (Stable Containers)

When containers are running but not working properly, jump inside:

docker compose exec -ti process /cnb/lifecycle/launcher bash

This gives you a shell inside the container where you can:

• Check environment variables: env | grep -E "(RAILS|DATABASE|SECRET)"
• Test database connections
• Run Rails console: rails console
• Check file permissions and paths
• Debug gem loading issues

Common Error Patterns

Database Connection Issues

could not connect to server: Connection refused

Solution: Verify DATABASE_URL environment variable and database server status.

Environment Variable Problems

Missing required environment variable: RAILS_MASTER_KEY

Solution: Ensure all required environment variables are set in your deployment configuration.

Pro Tips

• Start with logs - they usually point to the root cause
• Use container shell for interactive debugging
• Check environment variables first - most issues are configuration-related
• Test locally with the same environment variables if possible
• Keep deployment logs for future reference

Still Stuck?

If you can’t resolve the issue:

1. Save the full error logs
2. Note the exact error message and stack trace
3. Check if it’s a known issue in your framework’s documentation
4. Consider rolling back to a previous working deployment