Skip to main content
This guide covers advanced configuration options for Ralph, including LDAP/Active Directory authentication and OpenStack cloud synchronization.

​
Configuration Structure

​
Ubuntu Package Installation

Configuration files are located in /etc/ralph/:
  • /etc/ralph/ralph.conf - Main configuration
  • /etc/ralph/conf.d/database.conf - Database settings
  • /etc/ralph/conf.d/redis.conf - Redis cache settings
  • /etc/ralph/conf.d/gunicorn.conf - Gunicorn server settings
  • /etc/ralph/conf.d/cache.conf - Cache configuration
Settings are environment variables that Django reads on startup.

​
Docker Installation

Set environment variables in your docker-compose.yml file under the environment section.

​
LDAP Authentication

Ralph supports authentication via LDAP and Active Directory systems.

​
Installation

1

Install LDAP Requirements

Ubuntu:
pip install python-ldap django-auth-ldap
Docker: LDAP dependencies are included in the base image.
2

Configure LDAP Backend

Add LDAP as an authentication backend in your local settings file.Create /etc/ralph/conf.d/ldap.conf (Ubuntu) or add to environment:
AUTHENTICATION_BACKENDS = (
    'django_auth_ldap.backend.LDAPBackend',
    'django.contrib.auth.backends.ModelBackend',
)

LOGGING['loggers']['django_auth_ldap'] = {
    'handlers': ['file'],
    'propagate': True,
    'level': 'DEBUG',
}

​
Active Directory Configuration

Example configuration for Active Directory: 
import ldap
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType

# Server settings
AUTH_LDAP_SERVER_URI = "ldap://activedirectory.domain:389"
AUTH_LDAP_BIND_DN = "CN=ralph_service,OU=ServiceAccounts,DC=domain,DC=com"
AUTH_LDAP_BIND_PASSWORD = "your_secure_password"
AUTH_LDAP_PROTOCOL_VERSION = 3

# User search settings
AUTH_LDAP_USER_USERNAME_ATTR = "sAMAccountName"
AUTH_LDAP_USER_SEARCH_BASE = "DC=domain,DC=internal"
AUTH_LDAP_USER_SEARCH_FILTER = '(&(objectClass=user)({0}=%(user)s))'.format(
    AUTH_LDAP_USER_USERNAME_ATTR
)
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    AUTH_LDAP_USER_SEARCH_BASE,
    ldap.SCOPE_SUBTREE,
    AUTH_LDAP_USER_SEARCH_FILTER
)

# User attribute mapping
AUTH_LDAP_USER_ATTR_MAP = {
    "first_name": "givenName",
    "last_name": "sn",
    "email": "mail",
    "company": "company",
    "manager": "manager",
    "department": "department",
    "employee_id": "employeeID",
    "location": "officeName",
    "country": "ISO-country-code",
}

​
OpenDJ Configuration

For OpenDJ LDAP servers, use uid for username: 
AUTH_LDAP_USER_USERNAME_ATTR = "uid"

from django_auth_ldap.config import GroupOfUniqueNamesType

AUTH_LDAP_GROUP_TYPE = GroupOfUniqueNamesType()
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "DC=organization,DC=internal",
    ldap.SCOPE_SUBTREE,
    '(structuralObjectClass=groupOfUniqueNames)'
)

​
LDAP Group Mapping

Map LDAP groups to Ralph permissions: 
from ralph.account.ldap import MappedGroupOfNamesType

AUTH_LDAP_GROUP_MAPPING = {
    'CN=_gr_ralph,OU=Groups,DC=domain,DC=com': "staff",
    'CN=_gr_ralph_assets_buyer,OU=Groups,DC=domain,DC=com': "assets-buyer",
    'CN=_gr_ralph_assets_staff,OU=Groups,DC=domain,DC=com': "assets-staff",
    'CN=_gr_ralph_admin,OU=Groups,DC=domain,DC=com': "superuser",
}

AUTH_LDAP_MIRROR_GROUPS = True
AUTH_LDAP_GROUP_TYPE = MappedGroupOfNamesType(name_attr="cn")
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "DC=organization,DC=internal",
    ldap.SCOPE_SUBTREE,
    '(objectClass=group)'
)

​
Nested LDAP Groups

For nested group support: 
AUTH_LDAP_NESTED_GROUPS = {
    'CN=_gr_ralph_users,OU=Groups,DC=domain,DC=com': "staff",
}
AUTH_LDAP_QUERY_PAGE_SIZE = 500  # LDAP default page limit is 1000

​
User Filtering

Restrict which LDAP users can access Ralph: 
AUTH_LDAP_USER_FILTER = '(|(memberOf=CN=_gr_ralph_group1,OU=IT,' \
    'DC=domain,DC=com)(memberOf=CN=_gr_ralph_group2,OU=IT,' \
    'DC=domain,DC=com))'
For OpenDJ, use isMemberOf instead of memberOf.

​
Synchronize Users

Sync LDAP users to Ralph database: 
# Ubuntu
sudo ralphctl ldap_sync

# Docker
docker-compose exec web ralph ldap_sync
The script reports progress every 100 items.

​
ObjectClass Values by LDAP Implementation

  • Active Directory: objectClass=user
  • Novell eDirectory: objectClass=inetOrgPerson
  • OpenLDAP: objectClass=posixAccount

​
OpenStack Synchronization

Ralph supports one-way synchronization with OpenStack clouds, importing projects and instances in read-only mode.

​
Installation

1

Install OpenStack Requirements

Ubuntu:
pip install openstacksdk python-keystoneclient python-novaclient
Docker: OpenStack dependencies are included in the base Ralph image.
2

Configure OpenStack Instances

Add OpenStack configuration to your settings file.Create /etc/ralph/conf.d/openstack.conf or add to your local settings:
OPENSTACK_INSTANCES = [
    {
        'username':     'ralph_service',
        'password':     'secure_password',
        'tenant_name':  'admin',
        'version':      '2.0',
        'auth_url':     'http://openstack.example.com:35357/v2.0/',
        'tag':          'production'
    },
    {
        'username':     'ralph_service',
        'password':     'secure_password',
        'tenant_name':  'admin',
        'version':      '2.0',
        'auth_url':     'http://openstack-dev.example.com:35357/v2.0/',
        'tag':          'development'
    },
]
Configuration Parameters:
  • username: OpenStack user with permissions to list all projects and instances
  • tenant_name: Project/tenant for authentication
  • version: OpenStack API version (currently only 2.x supported)
  • auth_url: OpenStack Keystone API endpoint
  • tag: Tag added to all imported Cloud Projects and Cloud Hosts

​
Run Synchronization

Execute OpenStack sync manually: 
# Ubuntu
sudo ralphctl openstack_sync

# Docker
docker-compose exec web ralph openstack_sync

​
Automated Synchronization

Schedule regular syncs using cron (Ubuntu): 
# Edit crontab
sudo crontab -e

# Add sync every hour
0 * * * * /usr/bin/ralphctl openstack_sync >> /var/log/ralph/openstack_sync.log 2>&1
For Docker, use a scheduler container or external cron job: 
0 * * * * docker-compose -f /path/to/docker-compose.yml exec -T web ralph openstack_sync

​
How It Works

  1. First Run: Imports all Cloud Projects, Cloud Hosts, and Cloud Flavors from OpenStack
  2. Subsequent Runs: Updates existing objects and deletes those no longer in OpenStack
  3. Read-Only Import: Most fields are read-only; only Service Environment, Tags, and Remarks can be modified
  4. Inheritance: Cloud Host service environments inherit from their parent Cloud Project

​
Database Configuration

​
MySQL Configuration

Ubuntu (/etc/ralph/conf.d/database.conf): 
DATABASE_ENGINE=mysql
DATABASE_NAME=ralph_ng
DATABASE_USER=ralph_ng
DATABASE_PASSWORD=secure_password
DATABASE_HOST=localhost
DATABASE_PORT=3306
Docker (docker-compose.yml): 
services:
  web:
    environment:
      DATABASE_ENGINE: mysql
      DATABASE_NAME: ralph_ng
      DATABASE_USER: ralph_ng
      DATABASE_PASSWORD: secure_password
      DATABASE_HOST: db
      DATABASE_PORT: 3306

​
PostgreSQL Configuration

Ubuntu: 
DATABASE_ENGINE=postgresql
DATABASE_NAME=ralph_ng
DATABASE_USER=ralph_ng
DATABASE_PASSWORD=secure_password
DATABASE_HOST=localhost
DATABASE_PORT=5432

​
Redis Configuration

Ubuntu (/etc/ralph/conf.d/redis.conf): 
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=""
REDIS_TIMEOUT=10.0
REDIS_CONNECT_TIMEOUT=1.0

​
Redis Sentinel (High Availability)

REDIS_SENTINEL_ENABLED=1
REDIS_SENTINEL_HOSTS="sentinel1:26379,sentinel2:26379,sentinel3:26379"
REDIS_CLUSTER_NAME="ralph-master"
REDIS_SENTINEL_SOCKET_TIMEOUT=0.2

​
Gunicorn Configuration

Ubuntu (/etc/ralph/conf.d/gunicorn.conf): 
GUNICORN_BIND=0.0.0.0:8000
GUNICORN_WORKERS=4
GUNICORN_ACCESSLOG=/var/log/ralph/gunicorn.access.log
GUNICORN_ERRORLOG=/var/log/ralph/gunicorn.error.log
GUNICORN_LOGLEVEL=info
GUNICORN_USER=ralphsrv
GUNICORN_GROUP=ralphsrv
GUNICORN_TIMEOUT=30
Set GUNICORN_WORKERS to (2 * CPU_cores) + 1 for optimal performance.

​
Cache Configuration

Enable Redis caching for improved performance: Ubuntu (/etc/ralph/conf.d/cache.conf): 
# Store sessions in Redis
STORE_SESSIONS_IN_REDIS=1

# Use Redis for Django cache
USE_REDIS_CACHE=1

# Optional: Use different Redis DB for cache
REDIS_CACHE_DB=1
REDIS_CACHE_PASSWORD=""

​
Logging Configuration

Ubuntu (/etc/ralph/ralph.conf): 
LOG_FILEPATH=/var/log/ralph/ralph.log
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

​
Static Files and Media

STATIC_ROOT=/usr/share/ralph/static
MEDIA_ROOT=/var/local/ralph/media
After changing static file settings, collect static files: 
# Ubuntu
sudo ralphctl collectstatic --noinput

# Docker
docker-compose exec web ralph collectstatic --noinput

​
Security Settings

​
Debug Mode

Never enable debug mode in production!
# Development only
RALPH_DEBUG=1

# Production
RALPH_DEBUG=0

​
Allowed Hosts

For production, specify allowed hostnames: 
ALLOWED_HOSTS = ['ralph.example.com', 'ralph-internal.example.com']

​
Secret Key

Generate a unique secret key for your installation: 
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'
Add to configuration: 
SECRET_KEY='your-generated-secret-key-here'

​
Applying Configuration Changes

After modifying configuration: Ubuntu: 
sudo systemctl restart ralph.service
Docker: 
docker-compose restart web

​
Next Steps

Data Migration

Learn how to import data from Ralph 2 or other sources

Build docs developers (and LLMs) love

Get started for freeTalk to us