Troubleshooting common Docker manager issues

While Docker manager simplifies container deployment, you might occasionally encounter issues. This guide covers the most common problems and their solutions, helping you quickly resolve deployment or runtime issues.

How to access deployment logs

Before troubleshooting, it’s essential to know how to access detailed deployment logs:

Click the Browser terminal button in the top right corner
Navigate to your project’s build log:
```
cat /docker/[project-name]/.build.log
```
Replace [project-name] with your actual project name
Review the output for error messages or warnings

These logs contain valuable information about image pulling, container creation, and startup processes.

Common deployment issues

Issue 1: “Port already in use” error

Symptoms: Deployment fails with a message about port conflicts

Solutions:

Check which ports are in use:
```
sudo netstat -tlnp
```
Either:
- Choose a different port in your configuration
- Stop the conflicting service
- Modify your port mapping (e.g., change 80:80 to 8080:80)

Issue 2: “Image not found” error

Symptoms: Docker cannot pull the specified image

Solutions:

Verify the image name and tag:
- Correct format: image:tag (e.g., nginx:latest)
- Check for typos
Ensure the image exists on Docker Hub or the specified registry
For private images, ensure authentication is configured

Issue 3: Container starts but immediately stops

Symptoms: Container shows as “Exited” or keeps restarting

Solutions:

Check container logs via browser terminal:
```
docker logs [container-name]
```
Common causes:
- Missing environment variables
- Incorrect startup command
- Application crashes on startup
Verify all required environment variables are set
Check if the application needs specific file permissions

Common runtime issues

Issue 4: Cannot access the application via browser

Symptoms: Application seems to be running, but the web browser shows a connection error

Solutions:

Verify the correct port mapping:
- Check if you’re using the VPS port, not the container port
- URL format: http://your-vps-ip:vps-port
Check firewall rules:
```
sudo ufw status
```
Ensure the application is listening on the correct interface (0.0.0.0, not localhost)

Issue 5: Container running out of memory

Symptoms: Container crashes with “OOMKilled” status or the application becomes unresponsive

Solutions:

Check container resource usage:
```
docker stats [container-name]
```
Monitor VPS resources via the control panel
Consider:
- Upgrading your VPS plan
- Optimizing your application
- Setting memory limits in your compose file

Issue 6: Persistent data lost after container restart

Symptoms: Database or uploaded files disappear after container updates

Solutions:

Ensure you’ve configured volumes correctly:
- Format: /host/path:/container/path
- Use absolute paths on the host
Check volume permissions:
```
ls -la /path/to/volume
```

Verify volumes are properly mounted:

docker inspect [container-name] | grep -A 10 Mounts

Configuration issues

Issue 7: Invalid YAML syntax

Symptoms: Deployment fails with parsing errors

Solutions:

Use the YAML preview pane to spot issues
Common YAML mistakes:
- Incorrect indentation (use spaces, not tabs)
- Missing colons after keys
- Improper quotes around values
Validate your YAML using online tools before deployment

Issue 8: Environment variables not working

Symptoms: Application can’t find configuration values

Solutions:

Check environment variable format:
- Correct: KEY=value
- No spaces around the equals sign

For multi-line values, use proper YAML syntax:

environment:
 - KEY=value
 - MULTILINE_KEY=|
   line1
   line2

Verify inside container:
```
docker exec [container-name] env
```

Networking issues

Issue 9: Containers can’t communicate

Symptoms: Multi-container applications fail to connect to each other

Solutions:

Ensure containers are in the same compose project
Use service names for internal communication:
- Not: localhost:3306
- Correct: mysql:3306 (where mysql is the service name)

Check if containers are on the same network:

docker network ls docker inspect [network-name]

Issue 10: DNS resolution problems

Symptoms: Container can’t resolve external domains

Solutions:

Check DNS configuration:

docker exec [container-name] cat /etc/resolv.conf

Test DNS resolution:

docker exec [container-name] nslookup google.com

Configure custom DNS servers if needed in your compose file

Performance issues

Issue 11: Slow container startup

Symptoms: Containers take unusually long to start

Solutions:

Check if images are cached locally: bash
```
docker images
```
Monitor download speed during image pull
Consider using smaller base images (e.g., alpine variants)
Ensure your VPS has sufficient resources

Issue 12: Application running slowly

Symptoms: Application responds but performance is poor

Solutions:

Monitor resource usage: bash
```
docker stats htop
```
Check for:
- CPU throttling
- Memory swapping
- Disk I/O bottlenecks
Optimize your application or upgrade VPS resources

Debugging commands cheat sheet

Access these commands via the browser terminal:

# View all containers
docker ps -a

# Check container logs
docker logs [container-name] --tail 50 -f

# Access container shell
docker exec -it [container-name] /bin/sh

# View deployment logs
cat /docker/[project-name]/.build.log

# Check system resources
free -h
df -h
top

# Inspect container configuration
docker inspect [container-name]

# View Docker daemon logs
journalctl -u docker -n 100

Best practices to avoid issues

Test locally first: Deploy on your local machine before VPS
Start simple: Begin with single containers before multi-container setups
Use version tags: Specify exact versions instead of latest
Monitor resources: Keep an eye on VPS resource usage
Regular backups: Backup your volumes and configurations
Document changes: Keep track of what works for your setup

Remember, most Docker manager issues have straightforward solutions. Start with the deployment logs and work through the relevant troubleshooting steps.