Docker Development Environment

Set up Ralph for development using Docker containers for a consistent, isolated environment

This guide covers setting up Ralph using Docker containers. This approach provides a consistent development environment across different platforms and requires minimal local dependencies.

Prerequisites

Only Docker is required:

• Docker 24.0.0 or later
• docker-compose (usually bundled with Docker Desktop)

On Apple Silicon (M1/M2/M3) Macs, you’ll need to enable x86/amd64 emulation in Docker settings.

Quick Start

1. Clone the repository

   git clone https://github.com/allegro/ralph.git
   cd ralph
   
2. Start the containers

   Launch all services using docker-compose:

   docker-compose -f docker/docker-compose-local-dev.yml up
   

   This builds and starts:

   • web - Ralph application (port 8000)
   • db - MySQL 5.7 database
   • redis - Redis cache server
   • inkpy - Background job processor
   • nginx - Static file server (port 80)
3. Initialize the database (first run only)

   On first launch or after removing the database volume, initialize Ralph:

   docker exec docker-web-1 /opt/local/init-local-dev-ralph.sh
   

   This command may take several minutes to complete on first run.

   This script performs:

   • Database migrations (ralph migrate --noinput)
   • Menu synchronization (ralph sitetree_resync_apps)
   • Superuser creation (username: ralph, password: ralph)

Access Ralph

Once all services are running, access Ralph at:

http://localhost:80

Default credentials:

• Username: ralph
• Password: ralph

Docker Architecture

Service Overview

The docker/docker-compose-local-dev.yml defines these services:

docker/docker-compose-local-dev.yml

services:
  web:
    platform: linux/amd64
    build:
      context: ../
      dockerfile: docker/Dockerfile-local-dev
    ports:
      - "8000:8000"
    volumes:
      - ../.:/var/local/ralph
    environment:
      DATABASE_NAME: ralph_ng
      DATABASE_USER: ralph_ng
      DATABASE_PASSWORD: ralph_ng
      DATABASE_HOST: db
      REDIS_HOST: redis

Volume Mounts

The web container mounts your local source directory:

../.:/var/local/ralph

This means:

• Code changes are immediately reflected in the container
• You can edit files on your host machine
• No container rebuild needed for code changes

Database Persistence

Database data is stored in a Docker volume:

volumes:
  ralph_dbdata:

To reset the database:

docker-compose -f docker/docker-compose-local-dev.yml down -v
docker-compose -f docker/docker-compose-local-dev.yml up
# Re-initialize after restart
docker exec docker-web-1 /opt/local/init-local-dev-ralph.sh

Development Workflow

Rebuilding Static Assets

When you modify JavaScript, CSS, or install new npm packages:

docker exec docker-web-1 /opt/local/rebuild-local-dev-statics.sh

This script:

1. Runs npm install to update dependencies
2. Executes gulp to rebuild static files

Known Issue: Static file building may fail or hang on Apple Silicon using Rosetta emulation. If this occurs, try rebuilding the container or running static builds on the host machine instead.

Viewing Logs

Monitor all services:

docker-compose -f docker/docker-compose-local-dev.yml logs -f

View specific service logs:

docker-compose -f docker/docker-compose-local-dev.yml logs -f web

Running Django Management Commands

Execute Django commands inside the web container:

# Create migrations
docker exec docker-web-1 ralph makemigrations

# Run migrations
docker exec docker-web-1 ralph migrate

# Create superuser
docker exec docker-web-1 ralph createsuperuser

# Django shell
docker exec -it docker-web-1 ralph shell

Running Tests

Execute the test suite:

docker exec docker-web-1 test_ralph test

Run specific tests:

docker exec docker-web-1 test_ralph test ralph.assets.tests

Accessing the Container Shell

Open a bash session in the web container:

docker exec -it docker-web-1 bash

PyCharm IDE Integration

Ralph supports remote Python interpreter configuration in PyCharm Professional.

1. Add Docker interpreter

   1. Go to Settings → Project: ralph → Python Interpreter
   2. Click Add Interpreter → On Docker
   3. Select docker/Dockerfile-local-interpreter as the Dockerfile
   4. Change context folder to . (project root)
2. Configure platform (Apple Silicon only)

   If using Apple Silicon architecture:

   Under Options → Build options, add:

   --platform linux/amd64
   

   This requires amd64 emulation enabled in Docker Desktop.

3. Verify interpreter

   After clicking Next:

   • Verify the interpreter path is correct
   • Confirm all Ralph dependencies are detected

Container Build Details

The development Dockerfile (docker/Dockerfile-local-dev) is based on Ubuntu Jammy and includes:

System Packages

# Python 3.10 with development headers
python3.10-dev python3-pip python3-setuptools

# LDAP support
libldap2-dev libsasl2-dev

# Database clients
libmysqlclient21 libmysqlclient-dev

# Node.js 22.x for frontend builds
nodejs

Entry Point Script

The container runs /opt/local/docker-local-dev-entrypoint.sh:

docker/provision/docker-local-dev-entrypoint.sh

#!/bin/bash
set -e
pip3 install -r /var/local/ralph/requirements/dev.txt
cd /var/local/ralph
if [[ ! -d src/ralph/static/vendor || ! -d src/ralph/static/css ]]; then
  /opt/local/rebuild-local-dev-statics.sh
else
  echo "Statics found. Not attempting to recreate them"
fi
make run

This automatically:

1. Installs Python dependencies
2. Builds static files if missing
3. Starts the development server

Environment Variables

Customize container behavior with environment variables:

Variable	Default	Description
DATABASE_NAME	ralph_ng	Database name
DATABASE_USER	ralph_ng	Database username
DATABASE_PASSWORD	ralph_ng	Database password
DATABASE_HOST	db	Database host (service name)
REDIS_HOST	redis	Redis host (service name)
REDIS_PORT	6379	Redis port
REDIS_DB	0	Redis database number

Useful Commands

Container Management

# Start in background
docker-compose -f docker/docker-compose-local-dev.yml up -d

# Stop services
docker-compose -f docker/docker-compose-local-dev.yml down

# Restart specific service
docker-compose -f docker/docker-compose-local-dev.yml restart web

# Rebuild containers
docker-compose -f docker/docker-compose-local-dev.yml build --no-cache

Database Operations

# Access MySQL shell
docker exec -it docker-db-1 mysql -u ralph_ng -pralph_ng ralph_ng

# Dump database
docker exec docker-db-1 mysqldump -u ralph_ng -pralph_ng ralph_ng > backup.sql

# Restore database
docker exec -i docker-db-1 mysql -u ralph_ng -pralph_ng ralph_ng < backup.sql

Troubleshooting

Port Already in Use

If port 80 or 8000 is already bound:

ports:
  - "8080:8000"  # Change host port to 8080

Container Won’t Start

Check logs for errors:

docker-compose -f docker/docker-compose-local-dev.yml logs web

Common issues:

• Platform mismatch (use --platform linux/amd64 on ARM)
• Out of disk space
• Port conflicts

Static Files Not Building

On Apple Silicon, Node.js builds may hang. Try:

1. Build static files on host:

   npm install
   ./node_modules/.bin/gulp
   

2. Or disable Rosetta emulation in Docker settings

Database Connection Failed

Ensure the database container is healthy:

docker-compose -f docker/docker-compose-local-dev.yml ps db

Wait for MySQL to fully initialize (may take 30-60 seconds on first run).

Comparison with Local Setup

Aspect	Docker	Local
Setup Time	Fast	Moderate
System Dependencies	Minimal	Many
IDE Integration	Limited	Full
Performance	Good (slower on Mac)	Excellent
Debugging	More complex	Direct
Consistency	Identical across systems	Varies

Next Steps

Local Setup

Switch to local development setup

Architecture

Learn about Ralph’s architecture