Skip to content

Docker 4 Tips Tricks Troubleshooting

Jump to bottom
Ségolène Albouy edited this page Jul 22, 2026 · 3 revisions

4️⃣ Tips, Tricks & Troubleshooting 🐛

Tips

Docker vocabulary

Term Definition
container Instance of an image (running or stopped). Safe to remove if stopped; removing a running one stops the service.
image Template used to create containers. Safe to prune if unused; will need to be rebuilt or pulled again.
volume Persistent data storage (e.g. databases). ⚠️ Caution ⚠️ deletion is permanent and causes data loss.
network Communication layer between containers. Usually safe to prune, but may affect custom setups.

TLDR;

  • docker system prune -a → safe to prune regularly (containers & images)
  • Volumes → prune only if you are sure
  • Networks → generally safe, check custom configurations
  • "Unused" in docker means "not referenced by any container (running or stopped)"

Free up space

Docker uses A LOT of disk space. Clean up things once in a while.

# List docker disk usage
docker system df

# Remove all unused containers, networks, images, and cache (everything EXCEPT volumes)
docker system prune -a

# Remove all unused volumes (⚠️ can delete important data if volumes are no longer attached to a container)
docker volume prune
# Preview what will be deleted by volume pruning
docker volume ls -f dangling=true

# Remove all stopped containers
docker container prune

# Remove all unused images
docker image prune -a

Extra docs

Home-brewed Docker docs and notes made when developping AIKON are available here.

Troubleshooting

🐴 Proxy nightmare

If providing proxy URLs inside docker/.env (HTTP_PROXY / HTTPS_PROXY) wasn't enough to build the application, you may encounter issues such as:

  • Docker images not pulling properly (only for official images, i.e. postgres:14)
  • System packages/pip dependencies not downloading when building containers
  • Docker containers not starting properly
  • Network connectivity issues between containers
  • Unable to send email

Try the following solutions:

Use IP of the proxy server instead of the hostname

If proxy URL is http://proxy.example.com:3128:

nslookup proxy.example.com
# Look for Non-authoritative answer > Address

Use the IP address instead of the hostname in front/app/config/.env file

#HTTP_PROXY=http://proxy.example.com:3128
HTTP_PROXY=http://123.456.789.012:3128
#HTTPS_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://123.456.789.012:3128

Configure Docker daemon to use proxy

  1. Create/edit /etc/systemd/system/docker.service.d/http-proxy.conf and add the following sections: 
    [Service]
Environment="HTTP_PROXY=http://proxy.example.com:3128"
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1,172.16.0.0/16,172.17.0.0/16,192.168.0.0/16,10.0.0.0/8"
  2. Create/edit /etc/docker/daemon.json and add 
    {
   "proxies": {
       "http-proxy": "http://proxy.enpc.fr:3128",
       "https-proxy": "http://proxy.enpc.fr:3128",
       "no-proxy": "localhost,127.0.0.1,172.16.0.0/16,172.17.0.0/16,192.168.0.0/16,10.0.0.0/8"
   },
   "dns": ["8.8.8.8", "8.8.4.4"],
   "registry-mirrors": ["https://registry.docker-cn.com"]
}
  3. Restart Docker service 
    sudo systemctl daemon-reload
sudo systemctl restart docker

Configure proxy in Dockerfiles

In docker/Dockerfile, add these lines after the FROM statement:

ENV http_proxy=http://123.456.789.012:3128
ENV https_proxy=http://123.456.789.012:3128
ENV no_proxy=localhost,127.0.0.1,.aikon_network
ENV HTTP_PROXY=http://123.456.789.012:3128
ENV HTTPS_PROXY=http://123.456.789.012:3128
ENV NO_PROXY=localhost,127.0.0.1,.aikon_network

# Configure apt proxy
RUN echo 'Acquire::http::Proxy "http://123.456.789.012:3128";' > /etc/apt/apt.conf.d/proxy.conf && \
    echo 'Acquire::https::Proxy "http://123.456.789.012:3128";' >> /etc/apt/apt.conf.d/proxy.conf && \
    echo 'Acquire::CompressionTypes::Order:: "gz";' > /etc/apt/apt.conf.d/99disable-compressors && \
    echo 'APT::Get::AllowUnauthenticated "true";' >> /etc/apt/apt.conf.d/99disable-compressors

Configure extra_hosts

If some external service as an SMTP server is unreachable from the container, it is possible to map its address directly to its IP.

# get IP of Gmail SMTP servers
nslookup smtp.gmail.com

> Non-authoritative answer:
> Name: smtp.gmail.com
> Address: 74.125.206.109 # Use this IP
> ...

Update docker-compose.yml to to include extra_hosts

services:
  web:
    # ... existing configuration ...
    environment:
      ...
    extra_hosts:
      - "smtp.gmail.com:142.250.191.108"

Restart the container:

bash docker.sh restart <container_name>

Manual image pull

If you can't pull images from your Docker compose, as a last resort, pull them manually.

docker pull ubuntu:22.04
docker pull postgres:14
docker pull redis:6
docker pull nginx:latest

Rebuild your containers after applying any of these solutions:

bash docker.sh build

🐘 Postgres version mismatch

⚠️ WARNING: This section needs improvement and is not fully tested, proceed with caution and edit if you find issues.

This section addresses issues when your existing PostgreSQL data was created with a different version than the one specified in docker-compose.yml. If you encounter errors like:

  • Django container fails to start with database version errors
  • Error messages mentioning PostgreSQL version incompatibility
  • Database service health checks failing

Create backup of existing data

  1. Stop all services 
    cd aikon/front/docker
bash docker.sh stop
  2. Backup your existing database data and copy backup file path: 
    bash docker/backup/backup_data.sh
BACKUP_FILE="path/to/backup_file"
  3. Remove old PostgreSQL data 
    docker volume rm docker_pgdata
  4. Restore data from dump 
    DB_CONTAINER=$(docker compose ps -q db)
source "../app/config/.env"

docker exec -i -e PGPASSWORD="$POSTGRES_PASSWORD" "$DB_CONTAINER" \
    psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
    < "$BACKUP_FILE"
# docker exec -i front_db_1 pg_restore -U $DB_USER -d $DB_NAME < $BACKUP_FILE
  5. Verify restoration 
    docker exec -e PGPASSWORD="$POSTGRES_PASSWORD" \
    "$DB_CONTAINER" psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "\dt"

docker exec docker-web-1 /home/aikon/venv/bin/python /home/aikon/app/manage.py migrate
docker logs docker-web-1
docker logs docker-db-1

# If successful, rebuild search indices
curl -i localhost:${NGINX_PORT}/search/json-generation

💢 Redis

failed to bind port 0.0.0.0:6379/tcp [...] address already in use

  • Diagnostic: an instance of Redis is already running on the host machine

  • Test: run the following command to see if it is the cas

    • redis-cli ping. if it returns PONG, then Redis is still running and needs to be killed
    • sudo lsof -i -P -n | grep <redis_port> to see if the port is still in use

  • Fix:

    sudo systemctl stop redis

Project overview

Deployment

Web application

Utils

Clone this wiki locally