Ralph CLI

Command-line interface for managing Ralph installations

Ralph provides several command-line tools for managing your Ralph installation, running development servers, and executing various operations.

Available Commands

Ralph includes the following command-line entry points:

ralph

The main production command for running Ralph.

ralph <django-command> [options]

This command uses the production settings (ralph.settings.prod) and provides access to all Django management commands.

Common Usage:

# Run database migrations
ralph migrate

# Create a superuser
ralph createsuperuser

# Collect static files
ralph collectstatic

# Run the development server
ralph runserver 0.0.0.0:8000

# Open Django shell
ralph shell

# Create database backup
ralph dumpdata > backup.json

# Load data from backup
ralph loaddata backup.json

dev_ralph

Development version of Ralph with development-specific settings.

dev_ralph <django-command> [options]

This command uses development settings (ralph.settings.dev) which typically include:

• Debug mode enabled
• Development-specific middleware
• Verbose logging
• Development database settings

Example:

# Run development server with dev settings
dev_ralph runserver

# Run migrations with dev settings
dev_ralph migrate

test_ralph

Test runner for Ralph with test-specific settings.

test_ralph test [app_label[.TestCase[.test_method]]] [options]

This command uses test settings (ralph.settings.test) and forces their use regardless of environment variables. Test settings typically include:

• In-memory database for faster tests
• Disabled migrations
• Test-specific configurations

Examples:

# Run all tests
test_ralph test

# Run tests for a specific app
test_ralph test ralph.data_center

# Run a specific test case
test_ralph test ralph.data_center.tests.test_models.DataCenterAssetTest

# Run tests with verbosity
test_ralph test --verbosity=2

# Run tests and keep test database
test_ralph test --keepdb

validate_ralph

Cross-validation tool for Ralph data integrity.

validate_ralph [options]

This command validates data consistency across Ralph’s database, checking for:

• Orphaned records
• Invalid foreign key references
• Data integrity violations
• Configuration issues

Example:

# Run validation
validate_ralph

Django Management Commands

Ralph is built on Django, so all Django management commands are available through the Ralph CLI.

Database Commands

# Show migrations status
ralph showmigrations

# Create new migrations based on model changes
ralph makemigrations

# Apply migrations
ralph migrate

# Rollback to a specific migration
ralph migrate data_center 0005

# Show SQL for a migration
ralph sqlmigrate data_center 0006

User Management

# Create a superuser
ralph createsuperuser

# Change user password
ralph changepassword username

Static Files

# Collect static files to STATIC_ROOT
ralph collectstatic

# Collect static files without prompts
ralph collectstatic --noinput

# Find which static file would be used
ralph findstatic admin/css/base.css

Database Shell

# Open database shell
ralph dbshell

Python Shell

# Open Python shell with Django environment loaded
ralph shell

# Use IPython if available
ralph shell -i ipython

# Use BPython if available
ralph shell -i bpython

Ralph-Specific Commands

Ralph extends Django with custom management commands for specific operations.

LDAP Synchronization

Synchronize users from LDAP/Active Directory:

ralph ldap_sync

This command:

• Connects to configured LDAP server
• Imports users matching filter criteria
• Updates existing user information
• Syncs group memberships
• Reports progress every 100 items

See the Configuration section for LDAP setup details.

OpenStack Synchronization

Sync cloud resources from OpenStack:

ralph openstack_sync

This command:

• Connects to configured OpenStack instances
• Downloads projects and instances
• Creates/updates Cloud Projects and Cloud Hosts in Ralph
• Deletes resources no longer in OpenStack
• Tags resources with configured tags

See the Configuration section for OpenStack setup.

Data Import

Import data from various sources:

# Import from CSV/Excel files
ralph import --help

Environment Variables

Ralph CLI commands respect several environment variables:

DJANGO_SETTINGS_MODULE · string

Override the Django settings module. Default varies by command:

• ralph: ralph.settings.prod
• dev_ralph: ralph.settings.dev
• test_ralph: ralph.settings.test (forced)

RALPH_DEBUG · boolean

Enable debug mode. Not recommended for production.

DATABASE_URL · string

Database connection string (e.g., mysql://user:pass@localhost/dbname)

SECRET_KEY · string

Django secret key for cryptographic signing. Must be set in production.

Example:

# Run with specific settings
DJANGO_SETTINGS_MODULE=ralph.settings.local ralph runserver

# Run with custom database
DATABASE_URL=mysql://ralph:[e-mail]/ralph ralph migrate

Running in Production

Using systemd

Create a systemd service file (/etc/systemd/system/ralph.service):

[Unit]
Description=Ralph Asset Management
After=network.target postgresql.service

[Service]
Type=notify
User=ralph
Group=ralph
WorkingDirectory=/opt/ralph
Environment="DATABASE_URL=postgresql://ralph:password@localhost/ralph"
Environment="SECRET_KEY=your-secret-key-here"
ExecStart=/opt/ralph/venv/bin/gunicorn ralph.wsgi:application \
    --bind 0.0.0.0:8000 \
    --workers 4 \
    --timeout 300

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable ralph
sudo systemctl start ralph
sudo systemctl status ralph

Using Supervisor

Create a supervisor config (/etc/supervisor/conf.d/ralph.conf):

[program:ralph]
command=/opt/ralph/venv/bin/gunicorn ralph.wsgi:application --bind 0.0.0.0:8000 --workers 4
directory=/opt/ralph
user=ralph
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/ralph/ralph.log
environment=DATABASE_URL="postgresql://ralph:password@localhost/ralph",SECRET_KEY="your-secret-key"

Reload supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start ralph

Scheduled Tasks

Use cron or systemd timers for periodic tasks:

# Add to crontab
crontab -e

# Sync LDAP users daily at 2 AM
0 2 * * * /opt/ralph/venv/bin/ralph ldap_sync

# Sync OpenStack every hour
0 * * * * /opt/ralph/venv/bin/ralph openstack_sync

# Cleanup old sessions weekly
0 3 * * 0 /opt/ralph/venv/bin/ralph clearsessions

Debugging

Enable Verbose Output

Most commands support verbosity levels:

# Minimal output
ralph migrate --verbosity=0

# Normal output (default)
ralph migrate --verbosity=1

# Verbose output
ralph migrate --verbosity=2

# Very verbose output
ralph migrate --verbosity=3

Check Configuration

# Check for common issues
ralph check

# Check deployment settings
ralph check --deploy

# Check specific subsystem
ralph check --tag models

Database Queries

Monitor SQL queries during development:

# Show SQL for specific commands
ralph migrate --verbosity=3

# Or use Django Debug Toolbar in development

Getting Help

Get help for any command:

# General help
ralph help

# List all available commands
ralph help --commands

# Help for a specific command
ralph help migrate
ralph migrate --help