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 nameReview 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:80to8080: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/pathUse 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=valueNo spaces around the equals sign
For multi-line values, use proper YAML syntax:
environment:
- KEY=value
- MULTILINE_KEY=|
line1
line2Verify 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:3306Correct:
mysql:3306(wheremysqlis 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.,
alpinevariants)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
latestMonitor 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.