Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/allegro/ralph/llms.txt

Use this file to discover all available pages before exploring further.

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