Web Server Start Debug Port Configuration Issues

When your web process isn’t being detected as stable or properly routed by Caddy, it’s often due to incorrect port configuration.

The Problem

Blossom dynamically assigns ports to your web processes via the $PORT environment variable. If your application hardcodes a port number instead of using $PORT, Caddy cannot route traffic to your app.

Common Symptoms

• Web process shows as “unstable” or “restarting”
• App appears to start but isn’t accessible via your domain
• Health checks fail
• Caddy logs show connection refused errors

Debugging Steps

1. Check your app logs for port binding messages
2. SSH into your server and verify the process is listening on the correct port:

   docker compose exec -ti process netstat -tlnp
   

3. Verify environment variables:

   docker compose exec -ti process env | grep PORT
   

What to Look For

• Process binding to 0.0.0.0:$PORT (correct)
• Process binding to 127.0.0.1:3000 or hardcoded ports (incorrect)
• “Address already in use” errors
• Connection refused errors in Caddy logs

The web server needs to start and bind to 0.0.0.0 because the Host will be an external domain, ex: mydomain.com

Prevention

Always use environment variables for port configuration in production. Never hardcode port numbers in your application code.

Language and Framework Examples

Ensure your web process uses the $PORT environment variable:

Node.js/Express

const port = process.env.PORT || 3000;
app.listen(port);

Ruby/Rails

# In config/puma.rb or similar
port ENV['PORT'] || 3000

Python/Flask

import os
app.run(host='0.0.0.0', port=int(os.environ.get('PORT', 5000)))

Python/Django

# In settings.py
PORT = int(os.environ.get('PORT', 8000))

Next Steps

If your port configuration is correct but you’re still having routing issues, check Caddy Routing Debug Guide for comprehensive debugging steps.