10 Common Docker Mistakes and How to Avoid Them

Learning from Mistakes

Every Docker user makes mistakes when starting out. The good news is that most of these mistakes are predictable and avoidable. By learning from others' errors, you can build a more reliable homelab from day one.

Here are the ten most common Docker mistakes and how to avoid them.

1. Using the Latest Tag

The :latest tag seems convenient, but it's a recipe for disaster. When an image updates, your container might suddenly break with no clear reason why.

# Bad - unpredictable updates
image: nginx:latest

# Good - pinned version
image: nginx:1.25.3

Always pin your images to specific versions. This gives you control over when updates happen and makes rollbacks easy.

2. Not Using Restart Policies

Without restart policies, your containers won't survive a system reboot. Your homelab should be resilient.

# Add to every service
services:
  myapp:
    image: myapp:1.0
    restart: unless-stopped

Use unless-stopped for most services. It restarts containers automatically unless you explicitly stop them.

3. Storing Data in Containers

Containers are ephemeral by design. Any data stored inside a container is lost when the container is removed.

# Always use volumes for important data
services:
  database:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Use Docker volumes or bind mounts for any data that needs to persist. This includes databases, configuration files, and user uploads.

4. Hardcoding Secrets in Compose Files

Never put passwords directly in your docker-compose.yml, especially if you version control your configs.

# Bad
environment:
  DB_PASSWORD: supersecret123

# Good - use .env file
environment:
  DB_PASSWORD: ${DB_PASSWORD}

# In .env file (add to .gitignore!)
DB_PASSWORD=supersecret123

Use environment files and add them to .gitignore. For production, consider Docker secrets or a secrets manager.

5. Running as Root

Many containers run as root by default, which is a security risk. If a container is compromised, the attacker has root access.

# Specify a non-root user when possible
services:
  myapp:
    image: myapp:1.0
    user: "1000:1000"

Check if your image supports running as non-root. Many official images do with the right environment variables.

6. Exposing All Ports to Host

Not every container needs to be accessible from outside Docker. Internal services should communicate over Docker networks.

# Bad - exposes database to host
ports:
  - "5432:5432"

# Good - only expose what's needed
# Database only needs internal network access
# No ports section = only accessible within Docker network

Only expose ports for services that need external access. Use Docker networks for internal communication.

7. Ignoring Resource Limits

A misbehaving container can consume all system resources and crash your entire homelab.

services:
  myapp:
    image: myapp:1.0
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Set resource limits on containers, especially for untrusted or experimental services.

8. Not Using Health Checks

A running container doesn't mean a healthy application. Health checks let Docker know when your service is actually ready.

services:
  web:
    image: nginx:1.25
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

9. Using docker compose down -v Carelessly

The -v flag removes volumes along with containers. This deletes all your data!

# Dangerous - removes all data
docker compose down -v

# Safe - keeps volumes
docker compose down

# Remove only unused volumes
docker volume prune

Always double-check before using the -v flag. Make backups before running any destructive commands.

10. Not Cleaning Up

Docker accumulates unused images, containers, and volumes over time. This can fill up your disk quickly.

# Check disk usage
docker system df

# Remove unused data (careful!)
docker system prune

# Remove unused images
docker image prune -a

# Remove unused volumes (very careful!)
docker volume prune

Schedule regular cleanup or set up automatic cleanup in your homelab maintenance routine.

Build Better Habits

Avoiding these mistakes from the start will save you hours of debugging and prevent data loss. Take the time to set up your containers properly, and your homelab will be more reliable and secure.