Troubleshooting Guide

This guide helps you resolve common issues when using Suthep.

Common Issues

Configuration File Not Found

Error:

Configuration file not found: suthep.yml

Solution:

1. Ensure you're in the correct directory
2. Check if suthep.yml exists:

   ls -la suthep.yml

3. Create configuration file:

   suthep init

4. Or specify custom path:

   suthep deploy -f /path/to/config.yml

Port Already in Use

Error:

Error: Port 3000 is already in use

Solution:

1. Find what's using the port:

   sudo lsof -i :3000
   # or
   sudo netstat -tulpn | grep 3000

2. Stop the conflicting service or change the port in suthep.yml:

   services:
     - name: api
       port: 3001  # Changed from 3000

SSL Certificate Creation Failed

Error:

Failed to obtain SSL certificate for example.com

Solutions:

1. Check DNS Configuration

   nslookup example.com
   # Ensure domain points to your server IP

2. Verify Ports Are Open

   # Check if ports 80 and 443 are open
   sudo ufw status
   # or
   sudo iptables -L

3. Use Staging Mode for Testing

   certbot:
     staging: true  # Use staging to avoid rate limits

4. Check Domain Accessibility

   curl -I http://example.com
   # Should return HTTP response

5. Check Certbot Logs

   sudo tail -f /var/log/letsencrypt/letsencrypt.log

Nginx Configuration Errors

Error:

nginx: configuration file /etc/nginx/nginx.conf test failed

Solutions:

1. Test Nginx Configuration

   sudo nginx -t

2. Check Nginx Error Logs

   sudo tail -f /var/log/nginx/error.log

3. Check Generated Config Files

   ls -la /etc/nginx/sites-available/
   cat /etc/nginx/sites-available/example_com.conf

4. Verify Nginx Syntax

   sudo nginx -t -c /etc/nginx/nginx.conf

Docker Container Issues

Error:

Error: Docker container failed to start

Solutions:

1. Check Docker Status

   docker ps
   docker ps -a  # Show all containers

2. Check Container Logs

   docker logs <container-name>

3. Verify Docker Image

   docker images
   docker pull <image-name>  # Pull latest image

4. Check Port Conflicts

   docker ps | grep <port>

5. Remove Old Containers

   docker rm <container-name>

Health Check Failures

Error:

Health check failed for service api

Solutions:

1. Verify Health Check Endpoint

   curl http://localhost:3000/health

2. Check Service is Running

   # For Docker
   docker ps
   docker logs <container-name>
   
   # For non-Docker
   ps aux | grep <service>

3. Increase Health Check Timeout

   deployment:
     healthCheckTimeout: 60000  # Increase to 60 seconds

4. Verify Health Check Path

   services:
     - name: api
       healthCheck:
         path: /health  # Ensure this path exists

Permission Denied Errors

Error:

Permission denied: /etc/nginx/sites-available/example.conf

Solutions:

1. Use Sudo

   sudo suthep deploy

2. Check File Permissions

   ls -la /etc/nginx/sites-available/

3. Verify User Permissions

   groups  # Check your user groups

Service Not Accessible

Issue: Service deployed but not accessible via domain.

Solutions:

1. Check Nginx Status

   sudo systemctl status nginx

2. Verify Site is Enabled

   ls -la /etc/nginx/sites-enabled/
   # Should have symlink to sites-available config

3. Check DNS Resolution

   nslookup example.com
   dig example.com

4. Test Local Connection

   curl http://localhost:3000

5. Check Firewall

   sudo ufw status
   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp

Zero-Downtime Deployment Issues

Issue: Deployment causes downtime.

Solutions:

1. Verify Deployment Strategy

   deployment:
     strategy: rolling  # or blue-green

2. Check Container Health

   docker ps
   # Both old and new containers should be running during deployment

3. Monitor Nginx Reload

   sudo nginx -t  # Test before reload
   sudo systemctl reload nginx  # Graceful reload

Multiple Services on Same Domain

Issue: Path-based routing not working.

Solutions:

1. Verify Path Configuration

   services:
     - name: api
       path: /api  # Ensure path is set
     - name: ui
       path: /     # Root path

2. Check Nginx Config

   cat /etc/nginx/sites-available/example_com.conf
   # Should have location blocks for each path

3. Test Paths

   curl http://example.com/api/health
   curl http://example.com/

Debugging Tips

Enable Verbose Output

Some commands support verbose output. Check logs:

# Check Nginx logs
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/access.log

# Check Docker logs
docker logs <container-name>

# Check system logs
sudo journalctl -u nginx -f

Test Configuration

Before deploying, test your configuration:

# Validate YAML syntax
yamllint suthep.yml

# Test Nginx config
sudo nginx -t

# Test Docker image
docker run --rm <image-name>

Step-by-Step Deployment

Deploy step by step to isolate issues:

# 1. Deploy without Nginx
suthep deploy --no-nginx

# 2. Deploy without HTTPS
suthep deploy --no-https

# 3. Full deployment
suthep deploy

Getting Help

If you're still experiencing issues:

1. Check Logs

   • Nginx: /var/log/nginx/
   • Certbot: /var/log/letsencrypt/
   • Docker: docker logs <container>

2. Verify Configuration

   • Review suthep.yml syntax
   • Check all required fields are present
   • Validate port numbers and domains

3. Test Components Individually

   • Test Nginx manually
   • Test Docker containers
   • Test SSL certificates

4. Check System Resources

   # Check disk space
   df -h
   
   # Check memory
   free -h
   
   # Check CPU
   top

Prevention

To avoid common issues:

1. Use Staging for Testing

   certbot:
     staging: true

2. Validate Configuration

   suthep init  # Interactive validation

3. Test Before Production

   • Test on staging environment first
   • Verify all services work individually
   • Test deployment process

4. Monitor Health Checks

   • Set appropriate intervals
   • Monitor health check endpoints
   • Set reasonable timeouts

Next Steps

• Advanced Topics - Advanced configuration and optimization
• Examples - Review working examples

Previous: Examples | Next: Advanced Topics →