Features

Logging and debugging

View logs, debug issues, and monitor your deployments.

Viewing logs

Application logs

View logs for a role on a server:

odysseus logs your-server --role web

Options:

# Last 100 lines (default)
odysseus logs your-server --role web

# Last 500 lines
odysseus logs your-server --role web -n 500

# Follow logs in real-time
odysseus logs your-server --role web -f

# Logs since a time
odysseus logs your-server --role web --since 1h
odysseus logs your-server --role web --since "2024-01-15 10:00:00"

Accessory logs

View logs for accessories:

odysseus accessory logs your-server --name db
odysseus accessory logs your-server --name db -f
odysseus accessory logs your-server --name redis -n 200

Checking status

Deployment status

View overall status of a server:

odysseus status your-server

Output:

Server: your-server
Service: myapp

Web Containers:
  myapp-web-v1.2.0  running (healthy)  Up 2 days
  myapp-web-v1.1.0  stopped           Exited 2 days ago

Job Containers:
  myapp-jobs-v1.2.0  running (healthy)  Up 2 days

Accessories:
  db     postgres:16   running (healthy)
  redis  redis:7       running (healthy)

Caddy Routes:
  myapp.example.com → myapp-web-v1.2.0:3000
  SSL: valid (expires in 60 days)

List containers

View all containers for a service:

odysseus containers your-server

Output:

Containers for 'myapp' on your-server:
  myapp-web-v1.2.0    running   3000/tcp   Up 2 days
  myapp-web-v1.1.0    stopped              Exited 2 days ago
  myapp-jobs-v1.2.0   running              Up 2 days

Interactive debugging

Shell access

Start a shell in a running web container:

odysseus app shell your-server

This opens an interactive bash shell inside the container.

Run commands

Execute a command in the container:

odysseus app exec your-server --command "rails console"
odysseus app exec your-server --command "env | grep DATABASE"
odysseus app exec your-server --command "ps aux"

Console

Start your application's console:

odysseus app console your-server

By default runs rails console. Override with:

odysseus app console your-server --cmd "python manage.py shell"

Debugging deployments

Verbose mode

See detailed SSH commands during deployment:

odysseus deploy --verbose --image v1.0.0

Output shows every command:

[app.example.com] docker pull myregistry/myapp:v1.0.0
[app.example.com] docker run -d --name myapp-web-v1.0.0 ...
[app.example.com] Waiting for health check...
[app.example.com] curl -s localhost:2019/config/apps/http/servers/...

Dry run

See what would happen without making changes:

odysseus deploy --dry-run --image v1.0.0

Validate configuration

Check for configuration errors:

odysseus validate

Common issues

Container won't start

Symptoms: Deployment hangs at "Starting container..."

Debug steps:

  1. Check recent logs:
odysseus logs your-server --role web -n 200
  1. Try running manually:
odysseus app exec your-server --command "your-start-command"
  1. Check container status on server:
ssh your-server "docker ps -a | grep myapp"
ssh your-server "docker logs myapp-web-v1.0.0"

Health check failing

Symptoms: "Health check failed" or timeout

Debug steps:

  1. Check if app is responding:
odysseus app exec your-server --command "curl -v localhost:3000/health"
  1. Check app logs for errors:
odysseus logs your-server --role web -n 500
  1. Verify health endpoint works:
odysseus app exec your-server --command "wget -q -O- localhost:3000/health"

SSL certificate issues

Symptoms: "Unable to obtain certificate" or SSL warnings

Debug steps:

  1. Check DNS configuration:
dig myapp.example.com
  1. Verify server is reachable:
curl -v http://myapp.example.com
  1. Check Caddy logs on server:
ssh your-server "journalctl -u caddy -n 100"

Connection refused

Symptoms: Can't connect to application

Debug steps:

  1. Check container is running:
odysseus containers your-server
  1. Check port binding:
ssh your-server "docker port myapp-web-v1.0.0"
  1. Check Caddy routing:
ssh your-server "curl -s localhost:2019/config/apps/http/servers/"

Cleanup

Remove old containers

Odysseus keeps 2 recent containers by default. Clean up extras:

odysseus cleanup your-server

Prune images

Remove unused Docker images to free disk space:

odysseus cleanup your-server --prune-images

Output shows disk usage before and after:

Disk usage before: 15.2 GB
Removing old containers...
Pruning unused images...
Disk usage after: 8.4 GB
Freed: 6.8 GB

Log management

Application logging

Configure your app to log to stdout for Docker to capture:

# Rails
config.logger = Logger.new(STDOUT)
config.log_level = :info

// Node.js
console.log('Request received:', req.path)

Log rotation

Docker manages log rotation. Configure in /etc/docker/daemon.json on your server:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

External logging

For production, consider shipping logs to a service:

  • Datadog
  • Papertrail
  • Logtail
  • CloudWatch Logs

Configure via environment variables in your app.

Previous
Accessories
Next
deploy