Deploy OSRD

Learn how to deploy OSRD in various environments

1: Docker Compose

2: Kubernetes with Helm

First of all, we recommend learning about the containers architecture of OSRD.

We will cover how to deploy OSRD within the following setups:

Using docker compose on a single node.
Using helm on a kubernetes cluster.

It is also possible to deploy each service of OSRD manually on a system, but we will not cover this topic within this guide.

1 - Docker Compose

Using docker compose for single node deployment

The OSRD project includes a docker-compose.yml file designed to facilitate the deployment of a fully functional OSRD environment. Only intended for development purposes, this Docker Compose configuration could be adapted for quick, single-node deployments.

Disclaimer

This setup is designed for development only. For example no authentication is supported and the front-end is served in development mode (rebuilt on the fly). If you mean to deploy a production ready version of OSRD, please follow the Kubernetes-based deployment

Prerequisites

Before proceeding with the deployment, ensure that you have the following installed:

Docker
Docker Compose

Configuration Overview

The docker-compose.yml file defines the following services:

PostgreSQL: A PostgreSQL database with PostGIS extension.
Redis: A Redis server for caching.
Core: The core OSRD service.
Front: The front-end service for OSRD.
Editoast: A OSRD service responsible for various editorial functions.
Gateway: Serves as the gateway for the OSRD services.
Wait-Healthy: A utility service to ensure all services are healthy before proceeding.

Each service is configured with health checks, volume mounts and necessary environment variables.

Deployment Steps

Clone the Repository: First, clone the OSRD repository to your local machine.
Configuration: The default configuration requires setting an environment variable for the Editoast service: ROOT_URL. It should be set to the URL pointing to the Editoast service through the gateway. For example, “http://your-domain.com/api".
You can also adjust other environment variables if needed.
Build and Run: Navigate to the directory containing docker-compose.yml and run:

docker-compose up --build

This command builds the images and starts the services defined in the Docker Compose file.

Accessing Services

While all HTTP service are used through the gateway (http://localhost:4000), you can access directly each service using their exposed ports:

PostgreSQL: Accessible on localhost:5432.
Redis: Accessible on localhost:6379.
Core Service: Accessible on localhost:8080.
Front-End: Accessible on localhost:3000.
Editoast: Accessible on localhost:8090.

Notes and Considerations

This setup is designed for development and quick deployments. For production environments, additional considerations for security, scalability and reliability should be addressed.
Ensure that the POSTGRES_PASSWORD and other sensitive credentials are securely managed, especially in production deployments.

2 - Kubernetes with Helm

Using Helm for Kubernetes deployments

The OSRD project’s Helm Chart provides a flexible and efficient way to deploy OSRD services in a Kubernetes environment. This document outlines the configuration options available in the Helm Chart, focusing on each service component.

Prerequisites

Before proceeding with the deployment, ensure that you have the following installed:

A Kubernetes cluster up and running
A PostgreSQL database with PostGIS
A Redis server (used for caching)

The tileserver

Tileserver is the component responsible for generating vector map tiles. It is recommended to separate it from standard Editoast while running a production setup since Editoast cannot be scaled horizontally (it is stateful).

You can visualize the recommended deployment here:

flowchart TD
    gw["gateway"]
    front["front-end static files"]
    gw -- local file --> front
    
    browser --> gw
    gw -- HTTP --> editoast
    gw -- HTTP --> tileserver-1
    gw -- HTTP --> tileserver-2
    gw -- HTTP --> tileserver-n...
    editoast -- HTTP --> core

The Helm chart leverages Kubernete’s HorizontalPodAutoscaler in order to spawn as much tileserver as required for the current workload.

Chart Values Overview

The Helm Chart is configurable through the following values:

Core Service

core: Configuration for the core OSRD service.
- internalUrl: Internal URL for service communication.
- image: Docker image to use.
- pullPolicy: Image pull policy.
- replicaCount: Number of replicas.
- service: Service type and port configuration.
- resources, env, annotations, labels, nodeSelector, tolerations, affinity: Various Kubernetes deployment options.

Editoast Service

editoast: Configuration for the Editoast service.
- Includes similar options as core for Kubernetes deployment.
- init: Initialization configuration.

Tile Server

tileServer: Specialized Editoast service that serves only vector map tiles.
- enabled: Set to true to enable tile server functionality.
- image: Docker image to use (typically the same as Editoast).
- replicaCount: Number of replicas, allowing for horizontal scaling.
- hpa: Horizontal Pod Autoscaler configuration.
- Other standard Kubernetes deployment options.

Gateway

gateway: Configuration for the OSRD gateway.
- Includes service, ingress, and other Kubernetes deployment options.
- config: Specific configurations for authentication and trusted proxies.

Deployment

The chart is available at ghcr OCI repository. You can find 2 Helm charts:

Stable charts: oci://ghcr.io/osrd-project/charts/osrd
Dev charts: oci://ghcr.io/osrd-project/charts/osrd-dev

To deploy the OSRD services using this Helm Chart:

Configure Values: Adjust the values in the Helm Chart to suit your deployment needs.
Install Chart: Use Helm to install the chart into your Kubernetes cluster.
```
helm install osrd oci://ghcr.io/osrd-project/charts/osrd -f values.yml
```