Skip to main content
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:
VariableDefaultDescription
DATABASE_NAMEralph_ngDatabase name
DATABASE_USERralph_ngDatabase username
DATABASE_PASSWORDralph_ngDatabase password
DATABASE_HOSTdbDatabase host (service name)
REDIS_HOSTredisRedis host (service name)
REDIS_PORT6379Redis port
REDIS_DB0Redis 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

AspectDockerLocal
Setup TimeFastModerate
System DependenciesMinimalMany
IDE IntegrationLimitedFull
PerformanceGood (slower on Mac)Excellent
DebuggingMore complexDirect
ConsistencyIdentical across systemsVaries

​
Next Steps

Local Setup

Switch to local development setup

Architecture

Learn about Ralph’s architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us