Skip to main content
This guide covers installing Ralph on Ubuntu using the official Debian packages. This is the recommended method for production deployments.

​
Overview

The Ubuntu package installation provides:
  • Python 3.10+ runtime environment
  • Settings located in /etc/ralph
  • Database configuration via debconf prompts
  • ralphctl command for Ralph management
  • Systemd service for automatic startup and management

​
Prerequisites

  • Clean Ubuntu 18.04 Bionic or newer installation
  • Root or sudo access
  • Internet connection for package downloads

​
Installation Steps

1

Add Ralph Repository

Add the official Ralph package repository and GPG key:
curl -sL https://packagecloud.io/allegro/ralph/gpgkey | sudo apt-key add -
sudo sh -c "echo 'deb https://packagecloud.io/allegro/ralph/ubuntu/ bionic main' > /etc/apt/sources.list.d/ralph.list"
sudo apt-get update
2

Install Required Packages

Install Ralph along with MySQL and nginx:
sudo apt-get install mysql-server nginx ralph-core
During installation, you’ll be prompted for database settings via debconf. For testing, the default settings are fine. You can review them later in /etc/ralph/conf.d/database.conf.
3

Configure Nginx

Edit the nginx configuration file:
sudo nano /etc/nginx/sites-available/default
Replace the contents with:
server {
    listen 80;
    client_max_body_size 512M;

    proxy_set_header Connection "";
    proxy_http_version 1.1;
    proxy_connect_timeout  300;
    proxy_read_timeout 300;

    access_log /var/log/nginx/ralph-access.log;
    error_log /var/log/nginx/ralph-error.log;

    location /static {
        alias /usr/share/ralph/static;
        access_log        off;
        log_not_found     off;
        expires 1M;
    }

    # Uncomment to enable media file downloads
    #location /media {
    #    alias /var/local/ralph/media;
    #    add_header Content-disposition "attachment";
    #}

    location / {
        proxy_pass http://127.0.0.1:8000;
        include /etc/nginx/uwsgi_params;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
Restart nginx to apply changes:
sudo systemctl restart nginx.service
4

Configure Database

Create the Ralph database and user:
sudo mysql
In the MySQL prompt:
CREATE USER 'ralph_ng'@'127.0.0.1' IDENTIFIED BY 'ralph_ng';
GRANT ALL PRIVILEGES ON ralph_ng.* TO 'ralph_ng'@'127.0.0.1';
CREATE DATABASE ralph_ng;
EXIT;
For production, use a strong password instead of ‘ralph_ng’ and consider placing the database on a separate host.
5

Initialize Database

Run database migrations to create the schema:
sudo ralphctl migrate
Create your admin superuser:
sudo ralphctl createsuperuser
Optionally, load demo data for testing:
sudo ralphctl demodata
6

Start Ralph Service

Finalize the setup and start Ralph:
sudo ralphctl sitetree_resync_apps
sudo systemctl enable ralph.service
sudo systemctl start ralph.service
Ralph should now be running at http://localhost

​
Configuration Files

Ralph configuration is managed through environment variables stored in configuration files:
  • Main config: /etc/ralph/ralph.conf
  • Database: /etc/ralph/conf.d/database.conf
  • Redis: /etc/ralph/conf.d/redis.conf
  • Gunicorn: /etc/ralph/conf.d/gunicorn.conf
  • Cache: /etc/ralph/conf.d/cache.conf

​
Service Management

Ralph runs as a systemd service. Common management commands: 
# Check service status
sudo systemctl status ralph.service

# Start Ralph
sudo systemctl start ralph.service

# Stop Ralph
sudo systemctl stop ralph.service

# Restart Ralph
sudo systemctl restart ralph.service

# View service logs
sudo journalctl -u ralph.service -f

​
Troubleshooting

If something goes wrong, check these log files: 
# Ralph application logs
/var/log/ralph/ralph.log

# Gunicorn error logs
/var/log/ralph/gunicorn.error.log

# Gunicorn access logs
/var/log/ralph/gunicorn.access.log

# Nginx error logs
/var/log/nginx/ralph-error.log

# Nginx access logs
/var/log/nginx/ralph-access.log

​
Common Issues

Check the logs for errors:
sudo journalctl -u ralph.service -n 50
sudo tail -f /var/log/ralph/ralph.log
Common causes:
  • Database connection issues
  • Missing migrations
  • Port 8000 already in use
Verify database credentials in /etc/ralph/conf.d/database.conf and ensure:
  • MySQL service is running: sudo systemctl status mysql
  • Database user has proper permissions
  • Database exists: mysql -u ralph_ng -p -e "SHOW DATABASES;"
Ensure static files are collected and nginx can access them:
sudo ralphctl collectstatic --noinput
sudo chown -R www-data:www-data /usr/share/ralph/static

​
Next Steps

Once Ralph is installed:
  1. Configure Ralph for your environment - see Configuration Guide
  2. Set up SSL/TLS for production use
  3. Configure backups for your database
  4. Review security settings and change default passwords
  5. Explore the quick start guide to begin using Ralph

Configuration Guide

Learn how to configure LDAP, OpenStack sync, and other advanced features

Build docs developers (and LLMs) love

Get started for freeTalk to us