Quick Start Guide

Get started with Ralph in minutes - install, configure, and add your first assets

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

Docker Installation (Recommended)

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.