Skip to main content
This guide covers common Docker commands and workflows for developing the ESP Website.

​
Container Management

​
Starting and Stopping

docker compose up
Always run docker compose down before docker compose up --build to avoid build errors caused by symlinks in the mounted volume.

​
Clean Restart

To stop and delete the database (fresh start): 
docker compose down -v
The -v flag removes all data volumes, including the database. This cannot be undone.

​
Common Commands

​
Django Management Commands

Run any manage.py command using: 
docker compose exec web python esp/manage.py <command>

​
Examples

docker compose exec web python esp/manage.py shell_plus

​
Shell Access

docker compose exec web bash

​
Loading a Database Dump

If you have an existing database dump (e.g., from a previous development setup), you can load it into the Docker environment.
1

Start with a clean database

Remove the existing volume and bring the containers back up:
docker compose down -v
docker compose up
Wait a few seconds for PostgreSQL to initialize, then proceed.
2

Copy the dump into the container

docker cp /path/to/dump.sql $(docker compose ps -q db):/tmp/dump.sql
3

Load the dump

docker compose exec db psql -U esp devsite_django -f /tmp/dump.sql
If you see ownership or permission errors when loading a dump from a different environment, the --no-owner --no-acl flags on pg_restore will ignore those. For plain SQL dumps, you can safely ignore ALTER OWNER errors — the data will still load correctly.
4

Re-run migrations

Ensure the schema matches the current code:
docker compose exec web python esp/manage.py migrate

​
Troubleshooting

​
Port Already in Use

If port 8000 (or 5432 or 11211) is in use, either stop the conflicting service or change the port mapping in docker-compose.yml:
docker-compose.yml
web:
  ports:
    - "9000:8000"  # Maps host port 9000 to container port 8000

​
Database Connection Errors

The entrypoint script waits for PostgreSQL to be ready, but if you still see connection errors, try: 
docker compose restart web

​
Permission Issues with Mounted Volumes

On Linux, files created inside the container may be owned by root. Fix with: 
sudo chown -R $USER:$USER .

​
Stale Containers

If things seem broken after a git pull, try a clean rebuild: 
docker compose down -v
FORCE_SETUP=1 docker compose up --build

​
Build Fails with “Invalid File Request”

If you see an error like invalid file request esp/public/media/images during docker compose build, run docker compose down first to remove the symlinks created by the entrypoint: 
docker compose down
docker compose up --build

​
Docker Desktop Not Running (Windows/macOS)

Windows error: 
unable to get image … open //./pipe/dockerDesktopLinuxEngine:
The system cannot find the file specified.
macOS error: 
Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?
Both errors mean Docker Desktop is not running. Open Docker Desktop and wait until the icon in the system tray (Windows) or menu bar (macOS) shows it is ready. Verify by running: 
docker info
If this returns engine details without errors, retry docker compose up --build.
Windows only: If the issue persists, open Docker Desktop → Settings → General and ensure “Use the WSL 2 based engine” is checked, then click Apply & Restart.

​
Docker Compose Configuration

The docker-compose.yml defines three services:
docker-compose.yml
services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: devsite_django
      POSTGRES_USER: esp
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  memcached:
    image: memcached:alpine
    ports:
      - "11211:11211"

  web:
    build: .
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    depends_on:
      - db
      - memcached
    environment:
      VIRTUAL_ENV: /usr

volumes:
  postgres_data:

Build docs developers (and LLMs) love

Get started for freeTalk to us