Local Development Setup

Set up a local development environment for Ralph using Python virtual environments

This guide walks you through setting up a local development environment for Ralph without Docker. This approach gives you direct control over the Python environment and is ideal for debugging and active development.

This guide assumes you’re running a POSIX-compliant environment (Linux, macOS, or WSL on Windows).

Prerequisites

Ensure the following tools are installed on your system:

• Python 3.10 (Ralph requires Python >=3.10.0, <3.11)
• pip - Python package manager
• virtualenvwrapper - Virtual environment management
• Node.js (v8.10.0 - v11.7.0) - For building static assets
• npm (3.5.2 - 6.5.0) - JavaScript package manager
• mysql-client system library
  • macOS: brew install mysql
  • Ubuntu/Debian: apt-get install libmysqlclient-dev
• Docker & docker-compose - For running service dependencies (database, cache)

Installation Steps

1. Clone the repository

   Get the Ralph source code:

   git clone https://github.com/allegro/ralph.git
   cd ralph
   
2. Create a virtual environment

   Create and activate a Python virtual environment:

   mkvirtualenv -p "$(which python3)" ralph
   

   The environment will be activated automatically after creation. To activate it later:

   workon ralph
   
3. Install Python dependencies

   Install the development dependencies:

   pip install -r requirements/dev.txt
   

   You may need to install additional system libraries and build tools if compilation fails for certain packages.

   The development dependencies include useful tools like:

   • django-debug-toolbar - Debug panel for Django
   • ipdb, ipython, pudb - Interactive debuggers
   • ruff - Fast Python linter
   • django-silk - Performance profiling
4. Install JavaScript dependencies

   Install Node.js packages and build static assets:

   npm install
   

   Then build the static files using Gulp:

   ./node_modules/.bin/gulp
   

   You must rebuild static files every time you modify JavaScript, CSS, or other static assets.

5. Start required services

   Use Docker Compose to run the database and cache services:

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

   This starts:

   • MySQL 5.7 on port 3306 (or PostgreSQL on port 54320)
   • Redis 4.0 on port 6379
   • inkpy - Ralph’s background worker service

   The services will create:

   • Database: ralph_ng
   • User: ralph_ng / password: ralph_ng
   • Volumes stored in ./volumes/ directory
6. Configure Django settings

   Copy the local settings template:

   cp src/ralph/settings/local.template src/ralph/settings/local.py
   

   Set the Django settings module environment variable:

   export DJANGO_SETTINGS_MODULE="ralph.settings.local"
   

   Add this export to your shell profile (~/.bashrc, ~/.zshrc) to make it permanent.

7. Initialize the database

   Run database migrations and create a superuser:

   python setup.py develop
   dev_ralph migrate
   dev_ralph createsuperuser
   

   Follow the prompts to create your admin user credentials.

8. Initialize the menu structure

   Synchronize the site menu tree:

   make menu
   

   This runs ralph sitetree_resync_apps to set up navigation.

9. Start the development server

   Launch Ralph in development mode:

   make run
   

   This runs dev_ralph runserver_plus 0.0.0.0:8000 with auto-reload enabled.

Access Ralph

Open your browser and navigate to:

http://127.0.0.1:8000

Log in with the superuser credentials you created in step 6.

Development Workflow

Auto-reload

The development server automatically detects changes to Python files and reloads. You don’t need to restart manually.

Database Configuration

The default configuration in src/ralph/settings/local.template supports both MySQL and PostgreSQL. Switch between them using the DB_ENGINE environment variable:

POSTGRES = os.environ.get("DB_ENGINE") != "mysql"
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql" if POSTGRES else "django.db.backends.mysql",
        "NAME": os.environ.get("DATABASE_NAME", "ralph_ng"),
        "USER": os.environ.get("DATABASE_USER", "ralph_ng"),
        "PASSWORD": os.environ.get("DATABASE_PASSWORD", "ralph_ng"),
        "HOST": os.environ.get("DATABASE_HOST", "127.0.0.1"),
        "PORT": 54320 if POSTGRES else 3306,
    }
}

Useful Commands

Command	Description
make run	Start development server
make menu	Resync site tree navigation
make test	Run test suite
make coverage	Run tests with coverage report
make checks	Run ruff linter
make clean	Remove compiled Python files
./node_modules/.bin/gulp	Rebuild static assets

Troubleshooting

Python Package Build Failures

If you encounter errors installing Python packages, ensure you have the required system libraries:

Ubuntu/Debian:

sudo apt-get install python3.10-dev libldap2-dev libsasl2-dev libffi-dev libmysqlclient-dev

macOS:

brew install mysql openldap

Static Files Not Loading

If CSS/JS assets aren’t loading:

1. Verify Node.js and npm versions are compatible
2. Delete node_modules/ and reinstall: npm install
3. Rebuild static files: ./node_modules/.bin/gulp

Database Connection Issues

Verify services are running:

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

Check connectivity:

mysql -h 127.0.0.1 -u ralph_ng -pralph_ng ralph_ng

Next Steps

Docker Environment

Learn about Docker-based development

Architecture

Understand Ralph’s architecture