Packaging

​

Python Package (setup.py)

​

Package Configuration

from setuptools import find_packages, setup

setup(
    name="ralph",
    version=get_version(),
    author="Allegro.pl Sp. z o.o. and Contributors",
    author_email="[email protected]",
    description="Advanced Asset Management and DCIM system for data center and back office.",
    url="http://ralph.allegrogroup.com/",
    packages=find_packages("src"),
    package_dir={"": "src"},
    zip_safe=False,  # Templates are loaded from file path
    entry_points={
        "console_scripts": [
            "ralph = ralph.__main__:prod",
            "dev_ralph = ralph.__main__:dev",
            "test_ralph = ralph.__main__:test",
            "validate_ralph = ralph.cross_validator.__main__:main",
        ],
    },
)

​

Requirements

assert sys.version_info >= (3, 10), "Python 3.10+ required."

​

Entry Points

• ralph - Production server
• dev_ralph - Development server with additional features
• test_ralph - Test runner
• validate_ralph - Cross-validation tool

• back_office.transition_action.email_context - Email context for transitions
• account.views.get_asset_list_class - Custom asset list views
• ralph.cloud_sync_processors - Cloud synchronization processors

​

Version Generation

#!/bin/bash
LATEST_TAG=$(git describe --abbrev=0)
CURRENT_TAG=$(git describe)

generate_next_version() {
    current_dateversion=$(echo "${LATEST_TAG}" | cut -d '.' -f1)
    new_dateversion=$(date +"%Y%m%d")
    # ...
}

​

Debian Packages

​

Why dh_virtualenv?

• Installing all dependencies into a virtualenv
• Packaging the entire virtualenv as a .deb file
• Avoiding conflicts with system Python packages
• Simplifying dependency management

​

Package Details

• debhelper (>= 9)
• dh-virtualenv
• git
• libmysqlclient-dev
• python3 (>=3.10)
• libffi-dev
• nodejs (>= 22.0.0)
• npm

• python3 (>=3.10)
• libmysqlclient21
• python3-distutils
• debconf

• mysql-server
• redis

​

Building Packages

​

Building Snapshot Packages

make build-snapshot-package

ralph-core_<DATE>.<PATCH>-<BRANCH>-SNAPSHOT_amd64.deb

1. Builds a Docker container with build dependencies
2. Generates a snapshot changelog
3. Builds the package
4. Copies it to build/
5. Cleans up the container

​

Building Release Packages

make build-package

​

Publishing Packages

​

Docker Images

​

Available Images

make build-docker-image

• allegro/ralph:latest
• allegro/ralph:<VERSION>

• allegro/ralph-static-nginx:latest
• allegro/ralph-static-nginx:<VERSION>

• allegro/inkpy:<VERSION>

​

Building Snapshot Docker Images

make build-snapshot-docker-image

1. Build a snapshot Debian package
2. Build Docker images using the snapshot package
3. Tag images with snapshot version

​

Publishing Docker Images

# Publish release images
make publish-docker-image

# Publish snapshot images
make publish-docker-snapshot-image

​

Customizing Docker Repository

make build-docker-image DOCKER_REPO_NAME=mycompany

​

Package Ecosystem Design

​

Key Principles

1. No specific environment required: All operations can be performed using tools a regular Ralph developer already has
2. Docker-based builds: Everything runs in Docker containers to avoid platform dependencies
3. Container rebuilds: Containers are rebuilt for each operation to avoid IO performance issues with mounted volumes on certain platforms
4. Official repository: Packages are published to packagecloud.io, owned by Allegro
5. GitHub integration: Package publishing is triggered by creating GitHub releases

​

Why Docker for Building?

• Platform independence: Developers on macOS, Windows, or Linux can build packages
• Consistent environment: Same build environment for all maintainers
• No system pollution: Build dependencies don’t affect the host system
• Reproducible builds: Same Dockerfile produces same packages

​

Makefile Targets

​

Package Management

# Build snapshot package for testing
make build-snapshot-package

# Build release package for production
make build-package

# Release a new version (maintainers only)
make release-new-version

​

Docker Images

# Build Docker images
make build-docker-image
make build-snapshot-docker-image

# Publish Docker images
make publish-docker-image
make publish-docker-snapshot-image

​

Development

# Install dependencies
make install          # Production dependencies
make install-dev      # Development dependencies
make install-test     # Test dependencies
make install-docs     # Documentation dependencies

# Install JavaScript dependencies
make install-js

# Run the development server
make run

# Run tests
make test TEST=ralph.assets
make coverage

# Code quality
make flake           # Flake8 linting
make checks          # Ruff checks
make isort           # Import sorting

# Build documentation
make docs

​

Installation from Packages

​

Installing Debian Package

# Add packagecloud repository
curl -s https://packagecloud.io/install/repositories/allegro/ralph/script.deb.sh | sudo bash

# Install ralph-core
sudo apt-get install ralph-core

​

Installing from PyPI

pip install ralph-ng

​

Installing from Source

git clone https://github.com/allegro/ralph.git
cd ralph
make install

​

Best Practices

1. Use snapshot packages for testing: Never deploy snapshot packages to production
2. Verify package contents: After building, inspect the package to ensure all files are included
3. Test in containers: Use Docker to test packages in clean environments
4. Follow semantic versioning: Version numbers should reflect the release date and patch level
5. Document build dependencies: Keep debian/control and setup.py requirements in sync
6. Clean builds: Always use --force-rm with Docker builds to avoid stale layers

​

Troubleshooting

​

Build Fails with Missing Dependencies

​

Version Mismatch

git fetch --tags

​

Docker Build Timeout

​

Package Installation Fails

sudo apt-get install -f

​

Related Documentation

• Maintainer Tools - Tools for Ralph maintainers
• Development Environment - Setting up your development environment