guides: deployment

content/docs/explanation/containers-architecture/_index.en.md

@@ -0,0 +1,30 @@
+---
+title: "Containers architecture"
+linkTitle: "Containers architecture"
+weight: 10
+description: "How the containers works together and how they are built"
+---
+
+There is 3 main containers deployed in a standard OSRD setup:
+ - **Gateway** _(includes the frontend)_: Serves the front end, handles authentication, and proxies requests to the backend.
+ - **Editoast**: Acts as the backend that interacts with the front end.
+ - **Core**: Handles computation and business logic, called by Editoast.
+
+## Standard deployment
+
+The standard deployment can be represented with the following diagram.
+
+```mermaid
+flowchart TD
+    gw["gateway"]
+    front["front-end static files"]
+    gw -- local file --> front
+    
+    browser --> gw
+    gw -- HTTP --> editoast
+    editoast -- HTTP --> core
+```
+
+External requests are received by the gateway. If the path asked starts with `/api` it will be forwarded using HTTP to editoast, otherwise it will serve a file with the asked path. Editoast reach the core using HTTP if required.
+
+The gateway is not only a reverse proxy with the front-end bundle included, it also provides all the authentication mechanisms : using OIDC or tokens.

content/docs/guides/deploy/_index.en.md

@@ -0,0 +1,15 @@
+---
+title: "Deploy OSRD"
+linkTitle: "Deploy OSRD"
+weight: 10
+description: Learn how to deploy OSRD in various environments
+---
+
+First of all, we recommend learning about the [containers architecture of OSRD]({{< ref "/docs/guides/explanation/containers-architecture" >}}).
+
+We will cover how to deploy OSRD within the following setups:
+
+ - [Using docker compose]({{< ref "/docs/guides/deploy/docker-compose" >}}) on a single node.
+ - [Using helm]({{< ref "/docs/guides/deploy/docker-compose" >}}) on a kubernetes cluster.
+
+It's also possible to deploy manually each service of OSRD manually on a system, but we will not cover this topic within this guide.

content/docs/guides/deploy/docker-compose/_index.en.md

@@ -0,0 +1,56 @@
+---
+title: "Docker Compose"
+linkTitle: "Docker Compose"
+weight: 10
+description: 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 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:
+
+```bash
+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.
+

content/docs/guides/deploy/kubernetes/_index.en.md

@@ -0,0 +1,88 @@
+---
+title: "Kubernetes with Helm"
+linkTitle: "Kubernetes with Helm"
+weight: 10
+description: 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 rendering OpenStreetMap 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:
+
+```mermaid
+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](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) in order to spawn as much tileserver as required for the current workload.
+
+## Chart Values Overview
+
+The Helm Chart is highly 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 OpenStreetMap 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](https://github.com/osrd-project/osrd-chart/pkgs/container/charts%2Fosrd): `oci://ghcr.io/osrd-project/charts/osrd`
+ - [Dev charts](https://github.com/osrd-project/osrd-chart/pkgs/container/charts%2Fosrd-dev): `oci://ghcr.io/osrd-project/charts/osrd-dev`
+
+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.
+
+   ```bash
+   helm install osrd oci://ghcr.io/osrd-project/charts/osrd -f values.yml
+   ```
+