Skip to main content

​
What You’ll Learn

This guide walks you through:
  1. Installing Ralph using Docker (fastest method)
  2. Initial configuration and login
  3. Adding your first data center asset
  4. Exploring the DC visualization
  5. Managing licenses and support contracts
This tutorial takes approximately 20 minutes to complete. By the end, you’ll have a working Ralph instance with sample data.

​
Installation

The fastest way to get Ralph running is using Docker Compose.
1

Install Docker & Docker Compose

Ensure you have Docker and Docker Compose installed on your system.
docker --version
docker-compose --version
2

Clone the Repository

git clone https://github.com/allegro/ralph.git
cd ralph/contrib
3

Create Docker Compose Configuration

Copy the template configuration:
cp docker-compose.yml.tmpl docker-compose.yml
Edit docker-compose.yml to customize settings if needed.
4

Build Ralph

docker-compose build
5

Initialize the Database

Run this command only once to set up the database schema:
docker-compose run --rm web /root/init.sh
6

Load Demo Data (Optional)

Populate Ralph with demonstration data to explore features:
docker-compose run --rm web ralph demodata
7

Start Ralph

docker-compose up -d
Ralph will be accessible at http://127.0.0.1
The init.sh script should only be executed once during initial setup. Running it again will reset your database.

​
Ubuntu Installation (Production)

For production deployments on Ubuntu 18.04 or newer:
1

Add Ralph Repository

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 Ralph

sudo apt-get install mysql-server nginx ralph-core
When prompted, configure database settings. Default settings work for testing.
3

Create Database

sudo mysql

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;
4

Initialize Ralph

sudo ralphctl migrate
sudo ralphctl createsuperuser
sudo ralphctl demodata  # Optional: load sample data
5

Configure Nginx

Edit /etc/nginx/sites-available/default with the following configuration:
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;
    
    location /static {
        alias /usr/share/ralph/static;
        expires 1M;
    }
    
    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:
sudo systemctl restart nginx.service
6

Start Ralph

sudo ralphctl sitetree_resync_apps
sudo systemctl enable ralph.service
sudo systemctl start ralph.service
Access Ralph at http://localhost

​
First Login

After installation:
  1. Navigate to your Ralph instance (e.g., http://localhost)
  2. Log in with the superuser credentials you created
  3. You’ll see the Ralph dashboard
If you loaded demo data, you’ll see sample assets, services, and other resources already populated.

​
Adding Your First Data Center Asset

Let’s add a blade server that will serve as a load balancer.

​
Step 1: Create a Model

Before adding an asset, we need to define its model.
1

Navigate to Add Asset

Go to Data Center → Hardware → Add data center asset
2

Create Model

Click the + button next to the Model field.Fill in the model details:
  • Name: “Dell PowerEdge R620”
  • Category: Select from the tree menu (e.g., Server → Rack)
  • Type: Choose “data center”
  • Height (U): 2
Click Save
The Type field determines where the asset appears. “data center” assets show in DC modules, while “back office” assets appear in Back Office modules.

​
Step 2: Create Service Environment

Service Environments group assets by their business purpose and deployment stage.
1

Open Service Environment Selector

Click the magnifying glass icon next to the Service Environment field, then click Add Service Env.
2

Create a Service

Click the + button next to Service.Configure the service:
  • Name: “Load Balancing”
  • Active: ✓ (checked)
  • Business Owners: (optional) Select responsible users
  • Technical Owners: (optional) Select technical team leads
Click Save
3

Create Environments

Below the Service field, add environments:
  • “production”
  • “testing”
  • “development”
Select production for this asset.
4

Save Service Environment

Click Save to create the Service Environment.
The Service Environment model in Ralph: 
class ServiceEnvironment(BaseObject):
    service = models.ForeignKey(Service, on_delete=models.CASCADE)
    environment = models.ForeignKey(Environment, on_delete=models.CASCADE)
    
    def __str__(self):
        return "{} - {}".format(
            self.service.name, 
            self.environment.name
        )

​
Step 3: Specify Location

To visualize assets in the DC view, configure their physical location.
1

Create a Rack

Click + next to the Rack field.
  • Name: “Rack-A1”
  • Click + to create a Server Room: “DC1-MainRoom”
  • Orientation: Front
  • Leave grid position as default for now
Click Save
2

Set U Position

In the Position field, enter the U-level where the server is installed.
  • Position: 6 (installs at U6 in the rack)
  • Orientation: Front
Position 0 is reserved for accessories like PDUs or patch panels mounted on the back of the rack.The Slot field is used for blade chassis that contain multiple servers in a single U position.

​
Step 4: Complete the Asset

1

Fill Required Fields

Complete the remaining required fields:
  • Barcode: “BC123456” (or scan actual barcode)
  • Serial Number: “SN789012” (optional if barcode is provided)
  • Service Environment: Select the “Load Balancing - production” you created
2

Add Optional Details

Consider filling optional fields:
  • Hostname: “lb-prod-01.datacenter.local”
  • Remarks: “Primary load balancer for web tier”
  • Invoice Date: Purchase date
  • Price: Asset purchase price
3

Save the Asset

Click Save to create your first data center asset!
Congratulations! You’ve successfully:
  • ✓ Created a reusable asset model
  • ✓ Set up a service and environment structure
  • ✓ Configured a data center location (room and rack)
  • ✓ Added your first asset to Ralph

​
Exploring DC Visualization

Ralph’s DC visualization provides an interactive view of your data center infrastructure.

​
Viewing Your Data Center

1

Open DC Visualization

Navigate to Data Center → Visualization in the menu.
2

Find Your Rack

You should see your newly created rack displayed on the grid. The visualization shows:
  • Rack position in the room
  • Rack orientation (which direction it faces)
  • Rack name
3

Enter Edit Mode

Click the Edit button to:
  • Drag racks to new positions
  • Rotate racks using the rotation button
  • Rename racks by clicking the pencil icon
  • Add new racks by clicking the grid with the plus cursor
4

Adjust Grid Size

Extend the data center floor plan by changing the grid dimensions:
  • Edit Columns and Rows in the Data Center settings
  • This allows you to accommodate more racks

​
Inspecting Rack Contents

1

Click on Your Rack

Click on Rack-A1 to open the Rack Inspector.
2

View Front and Back

The inspector displays both sides of the rack:
  • Front view: Shows servers and equipment with front orientation
  • Back view: Shows equipment mounted on the rear, power distribution units
  • U positions: Numbered from bottom to top
3

See Your Asset

Your Dell PowerEdge R620 should be visible at U6, occupying 2U of space.Click on the asset to:
  • View quick details
  • Access the edit form
  • See related information (licenses, supports, network)
The DC visualization updates in real-time. Any changes to rack assignments or positions immediately reflect in the view.

​
Managing Software Licenses

Track software licenses and their assignments to ensure compliance.

​
Creating a License

1

Navigate to Licenses

Go to Licenses → Licenses → Add License
2

Create Software Entry

Click + next to Software field:
  • Name: “Microsoft Office 2019”
  • Asset Type: Select “All” (available for both DC and Back Office)
Click Save
3

Configure License Details

Fill in the license information:
  • License Type: “per user”
  • Software: “Microsoft Office 2019”
  • Inventory Number: Your internal tracking number
  • Region: Select your region (e.g., “Default”)
  • Serial Number: The license key
  • Number of Purchased Items: 10
  • Invoice Date: Purchase date
  • Price: Total cost for all licenses
4

Save the License

Click Save to create the license.
Example license model structure: 
from ralph.licences.models import Licence, Software

# Software represents the product
software = Software.objects.create(
    name="Microsoft Office 2019",
    asset_type="all"  # Available for all asset types
)

# Licence tracks the purchased licenses
licence = Licence.objects.create(
    software=software,
    licence_type="per_user",
    number_bought=10,
    sn="XXXXX-XXXXX-XXXXX-XXXXX"
)

​
Assigning Licenses

1

Open License Assignments

In your license detail view, click the Assignments tab.
2

Add Asset Assignment

For hardware-based licenses:
  • Search for your asset using barcode (“BC123456”)
  • Or use the magnifying glass to browse assets
  • Specify quantity if assigning multiple licenses
3

Add User Assignment

For per-user licenses:
  • Click the Assigned to Users tab
  • Select users from your directory
  • Each assignment decrements available licenses
4

Monitor Availability

Ralph automatically calculates free licenses:
  • Total: 10
  • Used: 3
  • Free: 7
The system prevents over-allocation.
When you reach 0 free licenses, Ralph will prevent additional assignments until you purchase more licenses or deallocate existing ones.

​
License Reports

Generate compliance and usage reports:
  1. Navigate to Reports → Licenses
  2. Select report type:
    • License usage summary
    • Expiring licenses
    • Over-allocated licenses
    • Cost analysis by department
  3. Export to PDF or CSV

​
Vendor Support Contracts

Track vendor support agreements, SLAs, and maintenance contracts.

​
Adding Support Contracts

1

Navigate to Supports

Go to Supports → Supports → Add Support
2

Create Support Entry

Configure the support contract:
  • Name: “Dell ProSupport Plus”
  • Contract ID: Vendor’s contract number
  • Asset: Select your server (search by barcode)
  • Support Type: “Vendor support” or “Warranty”
  • Status: “Active”
  • Date From: Contract start date
  • Date To: Contract end date
  • Price: Annual cost
3

Add Documentation

Attach contract documents:
  • Click Attachments tab
  • Upload PDF copies of support agreements
  • Add notes or special terms
4

Save Support Contract

Click Save to create the support record.
Ralph can send notifications when support contracts are approaching expiration, helping you plan renewals in advance.

​
Key Differences from Licenses

  • Asset-only: Supports attach to assets, not users
  • Status tracking: Mark contracts as Active, Expired, or Cancelled
  • SLA terms: Store response time and resolution commitments
  • Renewal tracking: Monitor expiration dates

​
Next Steps

You now have a working Ralph instance with:
  • ✓ Data center assets with location tracking
  • ✓ Service and environment organization
  • ✓ Software license management
  • ✓ Vendor support tracking

​
Continue Your Journey

Back Office Assets

Learn to manage laptops, desktops, and mobile devices

Network Management

Configure IP addresses, DHCP, and DNS integration

Workflow System

Create custom transitions for asset lifecycle automation

API Integration

Integrate Ralph with your existing tools via REST API

Custom Fields

Extend Ralph’s data model for your specific needs

Reports

Generate compliance and asset utilization reports

​
Get Help

Community Forum

Ask questions and share knowledge with the Ralph community

GitHub Issues

Report bugs or request features

​
Troubleshooting

​
Common Issues

Ralph won’t start Check log files: 
# Docker installation
docker-compose logs web

# Ubuntu installation
tail -f /var/log/ralph/ralph.log
tail -f /var/log/ralph/gunicorn.error.log
Database connection errors Verify database credentials in:
  • Docker: docker-compose.yml
  • Ubuntu: /etc/ralph/conf.d/database.conf
Can’t access on port 80 Ensure no other service is using port 80: 
sudo netstat -tulpn | grep :80
Static files not loading For Ubuntu installations: 
sudo ralphctl collectstatic
sudo systemctl restart ralph.service
For production deployments, review the security checklist in the Configuration guide and configure HTTPS, change default passwords, and set up proper firewall rules.

Build docs developers (and LLMs) love

Get started for freeTalk to us