This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Deploy OSRD

Learn how to deploy OSRD in various environments

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

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

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. Primarily intended for development purposes, this Docker Compose configuration can also be adapted for quick, single-node deployments.

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:

  1. PostgreSQL: A PostgreSQL database with PostGIS extension.
  2. Redis: A Redis server for caching.
  3. Core: The core OSRD service.
  4. Front: The front-end service for OSRD.
  5. Editoast: A OSRD service responsible for various editorial functions.
  6. Gateway: Serves as the gateway for the OSRD services.
  7. 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

  1. Clone the Repository: First, clone the OSRD repository to your local machine.
  2. Environment Variables (optional): Set necessary environment variables if you need to adjust some configurations.
  3. 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:

To deploy the OSRD services using this Helm Chart:

  1. Configure Values: Adjust the values in the Helm Chart to suit your deployment needs.

  2. 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