Skip to main content
This guide will help you set up a local development environment for the ESP Website. The recommended approach is using Docker, which requires minimal dependencies and works consistently across all platforms.

​
Prerequisites

Install Docker Desktop, which includes Docker Engine and Docker Compose in a single installer.
No Python, Node.js, PostgreSQL, or any other dependency needs to be installed on your host machine when using Docker.

​
Docker Architecture

The Docker setup runs three containers:
  • web: The Django application (Python 3.7)
  • db: PostgreSQL 14 database
  • memcached: Memcached caching layer
Your working copy is mounted into the container, so you can edit code with your preferred editor on your host machine and see changes reflected immediately.

​
Quick Start

1

Clone the repository

git clone https://github.com/learning-unlimited/ESP-Website.git devsite
cd devsite
2

Build and start services

docker compose up --build
The first build will take several minutes as it installs system and Python dependencies. Subsequent starts will be much faster due to Docker layer caching.
3

Wait for automatic setup

The entrypoint script will automatically (on first run):
  • Create local_settings.py from the Docker template
  • Create media symlinks (images, styles)
  • Wait for PostgreSQL to be ready
  • Run database migrations
  • Collect static files
On subsequent runs, migrations and static file collection are skipped for faster startup.
To force setup steps to run again (e.g., after pulling new code):
FORCE_SETUP=1 docker compose up
4

Access the site

Once you see Starting development server at http://0.0.0.0:8000/, open your browser and navigate to:
http://localhost:8000
5

Create an admin account

Open a new terminal and run:
docker compose exec web python esp/manage.py createsuperuser

​
Configuration

The Docker setup uses esp/esp/local_settings.py.docker as the template for local_settings.py. It is automatically copied on first run.

​
Key Configuration Differences

The Docker configuration includes:
  • DATABASES['default']['HOST'] is 'db' (the Docker service name) instead of 'localhost'
  • CACHES['default']['LOCATION'] is 'memcached:11211' instead of '127.0.0.1:11211'
  • ALLOWED_HOSTS is ['*'] for convenience in local development

​
Customizing Settings

If you need to customize settings:
  1. Edit esp/esp/local_settings.py directly (it is gitignored)
  2. Or edit esp/esp/local_settings.py.docker to change the defaults for all Docker users

​
Next Steps

Docker Commands

Learn common Docker commands for development

Contributing

Read the contribution workflow and guidelines

Build docs developers (and LLMs) love

Get started for freeTalk to us