From e65601ede143536975bcc0c471d84fea76da136a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89lys=C3=A6?= <101974839+ElysaSrc@users.noreply.github.com> Date: Thu, 23 Nov 2023 15:48:53 +0100 Subject: [PATCH] guides: deployment --- .../containers-architecture/_index.en.md | 30 +++++++ content/docs/guides/deploy/_index.en.md | 15 ++++ .../guides/deploy/docker-compose/_index.en.md | 56 ++++++++++++ .../guides/deploy/kubernetes/_index.en.md | 88 +++++++++++++++++++ 4 files changed, 189 insertions(+) create mode 100644 content/docs/explanation/containers-architecture/_index.en.md create mode 100644 content/docs/guides/deploy/_index.en.md create mode 100644 content/docs/guides/deploy/docker-compose/_index.en.md create mode 100644 content/docs/guides/deploy/kubernetes/_index.en.md diff --git a/content/docs/explanation/containers-architecture/_index.en.md b/content/docs/explanation/containers-architecture/_index.en.md new file mode 100644 index 000000000..9904f19ba --- /dev/null +++ b/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. \ No newline at end of file diff --git a/content/docs/guides/deploy/_index.en.md b/content/docs/guides/deploy/_index.en.md new file mode 100644 index 000000000..3441a95a5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/content/docs/guides/deploy/docker-compose/_index.en.md b/content/docs/guides/deploy/docker-compose/_index.en.md new file mode 100644 index 000000000..d0d34ebd9 --- /dev/null +++ b/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. + diff --git a/content/docs/guides/deploy/kubernetes/_index.en.md b/content/docs/guides/deploy/kubernetes/_index.en.md new file mode 100644 index 000000000..84acf062d --- /dev/null +++ b/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 + ``` +