Troubleshooting

Cannot connect via SSH

Symptoms: SSH connection times out or is refused.

Check the following:

1. Your EC2 security group allows inbound TCP port 22 from your IP address
2. The correct key pair was selected when launching the instance
3. The instance status checks have passed (2/2) — visible in the EC2 console

# Test from your local machine
ssh -v -i your-key.pem ubuntu@<ec2-ip>

Docker service not running

Symptoms: docker: command not found or Cannot connect to the Docker daemon.

# Check the Docker service status
sudo systemctl status docker

# Start it if it's not running
sudo systemctl start docker

# Enable it to start on boot
sudo systemctl enable docker

Permission denied running Docker commands

By default, Docker requires root or membership in the docker group.

# Add your user to the docker group (re-login required)
sudo usermod -aG docker ubuntu
newgrp docker

# Verify
docker ps

Cloud-init script did not run

If your EC2 user data script did not execute:

# View cloud-init output log
sudo cat /var/log/cloud-init-output.log

# Check cloud-init status
sudo cloud-init status

# View the script that ran
sudo cat /var/lib/cloud/instance/user-data.txt

Common causes: syntax errors in the script, missing #!/bin/bash shebang, or the script not being marked executable.

Container exits immediately

# View container logs
docker logs <container-name>

# Run interactively to debug
docker run -it --rm your-image bash