Skip to main content
This guide covers deploying Ralph using Docker containers. This method is ideal for development, testing, and containerized production environments.

​
Overview

The Docker installation uses official Ralph images:
  • allegro/ralph:latest - Main Ralph application
  • allegro/ralph-static-nginx:latest - Nginx server for static files
  • mysql:5.7 - Database server
  • redis:3.0 - Cache and task queue

​
Prerequisites

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • 4GB+ RAM available for containers
  • 10GB+ disk space

​
Quick Start

1

Install Docker and Docker Compose

If you don’t have Docker installed, follow the official installation guide:Verify installation:
docker --version
docker-compose --version
2

Create Docker Compose Configuration

Create a new directory for Ralph and a docker-compose.yml file:
mkdir ralph-docker
cd ralph-docker
nano docker-compose.yml
Add the following configuration:
docker-compose.yml
version: '3'
services:
  web:
    platform: linux/amd64
    image: allegro/ralph:latest
    restart: always
    ports:
      - "8000"
    volumes:
      - ralph_media:/var/local/ralph/media
      - ralph_static:/usr/share/ralph/static
    links:
      - db
      - redis
      - nginx
    environment:
      DATABASE_NAME: ralph_ng
      DATABASE_USER: ralph_ng
      DATABASE_PASSWORD: ralph_ng
      DATABASE_HOST: db
      REDIS_HOST: redis
      REDIS_PASSWORD: ""
      REDIS_PORT: 6379
      REDIS_DB: 0

  nginx:
    platform: linux/amd64
    image: allegro/ralph-static-nginx:latest
    restart: always
    ports:
      - "80:80"
    volumes:
      - ralph_media:/opt/media

  db:
    platform: linux/amd64
    image: mysql:5.7
    environment:
      MYSQL_DATABASE: ralph_ng
      MYSQL_ROOT_PASSWORD: ralph_ng
      MYSQL_USER: ralph_ng
      MYSQL_PASSWORD: ralph_ng
    volumes:
      - ralph_dbdata:/var/lib/mysql
    command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

  redis:
    platform: linux/amd64
    image: redis:3.0
    restart: always
    ports:
      - "6379"

  inkpy:
    platform: linux/amd64
    image: allegro/ralph:latest
    restart: always
    links:
      - redis:redis
    environment:
      REDIS_HOST: redis
      REDIS_PASSWORD: ""
      REDIS_PORT: 6379
      REDIS_DB: 0

volumes:
  ralph_dbdata:
  ralph_media:
  ralph_static:
This configuration uses default passwords. For production, change all passwords to strong, unique values.
3

Pull Docker Images

Download the required Docker images:
docker-compose pull
4

Initialize Database

Initialize the Ralph database (run this only once):
docker-compose run --rm web /var/local/ralph/init-ralph.sh init
This will:
  • Run database migrations
  • Sync the application menu tree
  • Create a default superuser
The initialization script will prompt you to create a superuser account. Save these credentials securely.
5

Load Demo Data (Optional)

To populate Ralph with demonstration data:
docker-compose run --rm web ralph demodata
6

Start Ralph

Start all services:
docker-compose up -d
Ralph will be available at:
If using Docker Toolbox or boot2docker, use $(docker-machine ip) instead of localhost.

​
Container Management

​
View Running Containers

# List all containers
docker-compose ps

# View logs from all services
docker-compose logs -f

# View logs from specific service
docker-compose logs -f web

​
Stop and Start Services

# Stop all services
docker-compose stop

# Start all services
docker-compose start

# Restart all services
docker-compose restart

# Stop and remove containers
docker-compose down

​
Upgrade Ralph

1

Pull Latest Images

docker-compose pull
2

Run Upgrade Script

docker-compose run --rm web /var/local/ralph/init-ralph.sh upgrade
3

Restart Services

docker-compose up -d

​
Environment Variables

Customize Ralph by setting environment variables in the docker-compose.yml file:

​
Database Configuration

environment:
  DATABASE_NAME: ralph_ng        # Database name
  DATABASE_USER: ralph_ng        # Database username
  DATABASE_PASSWORD: ralph_ng    # Database password
  DATABASE_HOST: db              # Database host
  DATABASE_PORT: 3306           # Database port (optional)
  DATABASE_ENGINE: mysql        # mysql or postgresql

​
Redis Configuration

environment:
  REDIS_HOST: redis             # Redis server host
  REDIS_PORT: 6379              # Redis port
  REDIS_DB: 0                   # Redis database number
  REDIS_PASSWORD: ""            # Redis password (if set)

​
Additional Settings

environment:
  RALPH_DEBUG: 0                # Debug mode (0 or 1)
  STATIC_ROOT: /usr/share/ralph/static
  MEDIA_ROOT: /var/local/ralph/media
  LOG_FILEPATH: /var/log/ralph/ralph.log

​
Data Persistence

Data is stored in Docker volumes to persist across container restarts:
  • ralph_dbdata - MySQL database files
  • ralph_media - User-uploaded media files
  • ralph_static - Static assets (CSS, JS, images)

​
Backup Volumes

# Backup database
docker-compose exec db mysqldump -u ralph_ng -pralph_ng ralph_ng > backup.sql

# Restore database
docker-compose exec -T db mysql -u ralph_ng -pralph_ng ralph_ng < backup.sql

​
Advanced Configuration

​
Using PostgreSQL Instead of MySQL

services:
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: ralph_ng
      POSTGRES_USER: ralph_ng
      POSTGRES_PASSWORD: ralph_ng
    volumes:
      - ralph_dbdata:/var/lib/postgresql/data

  web:
    environment:
      DATABASE_ENGINE: postgresql
      DATABASE_NAME: ralph_ng
      DATABASE_USER: ralph_ng
      DATABASE_PASSWORD: ralph_ng
      DATABASE_HOST: db
      DATABASE_PORT: 5432

​
Running Behind a Reverse Proxy

If running behind nginx or another reverse proxy: 
services:
  nginx:
    ports:
      - "8080:80"  # Change port binding
Configure your reverse proxy to forward requests to http://localhost:8080.

​
Troubleshooting

Check for port conflicts:
# Check if port 80 is in use
sudo lsof -i :80

# Check Docker logs
docker-compose logs
Ensure Docker has enough resources (memory, disk space).
The database container may take time to initialize:
# Wait for database to be ready
docker-compose logs db

# Restart web container after db is ready
docker-compose restart web
Ensure volumes are properly mounted:
docker-compose down -v  # Remove volumes
docker-compose up -d    # Recreate with fresh volumes
docker-compose run --rm web ralph collectstatic --noinput
On Linux, you may need to adjust volume permissions:
# Find the volume path
docker volume inspect ralph-docker_ralph_media

# Adjust permissions (use the path from above)
sudo chown -R 1000:1000 /var/lib/docker/volumes/ralph-docker_ralph_media

​
Next Steps

Configuration

Configure LDAP, OpenStack sync, and advanced features

Data Migration

Import existing data or migrate from Ralph 2

Build docs developers (and LLMs) love

Get started for freeTalk to us