docs: add a docker install guide

content/docs/guides/contribute/install-docker.en.md

@@ -0,0 +1,50 @@
+---
+title: "Install docker"
+linkTitle: "Install docker"
+weight: 15
+---
+
+Regardless of your operating system, docker requires linux to operate. When used on a different
+operating system, docker relies on virtual machines to build and run images.
+
+There are two main types of docker installations:
+- docker engine is the usual docker command line application
+- docker desktop is a GUI app that also manages virtualization
+
+Here's what we suggest:
+- If you're on linux, install docker engine [using your package manager](https://docs.docker.com/engine/install/#supported-platforms)
+- If you're on MacOS / Windows, install [docker desktop](https://www.docker.com/products/docker-desktop/) if you are allowed to
+- If you're on windows and want to get docker running within WSL, or can't use docker desktop, follow the [docker on WSL tutorial](#docker-on-wsl)
+- If you're on MacOS and can't use docker desktop, follow the [MacOS colima tutorial](#macos-colima)
+
+
+## Docker on WSL
+
+This install option is very useful, as it allows having a perfectly normal linux install of docker engine inside WSL, which can still be reached from windows.
+
+- [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (If you had an old version of WSL, run `wsl --upgrade`)
+- Get an operating system image from the microsoft store (for example, debian or ubuntu)
+- [Enable systemd support within the WSL VM](https://learn.microsoft.com/en-us/windows/wsl/systemd)
+- Follow the regular [linux install tutorial for docker](https://docs.docker.com/engine/install/#supported-platforms)
+- If you have docker desktop installed, you can [configure it to use WSL](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers)
+
+
+## MacOS colima
+
+This procedure allows installing docker without relying on docker desktop.
+It uses colima for virtualizing linux.
+
+1) [Install homebrew](https://brew.sh/)
+2) `brew install docker docker-compose colima`
+3) [Configure colima](https://github.com/abiosoft/colima?tab=readme-ov-file#customizing-the-vm):
+  - for apple silicon (M1/M2) macbooks: `colima start --cpu 2 --memory 6 --arch aarch64 --vm-type=vz --vz-rosetta --mount-type=virtiofs`
+  - for small infrastructures: `colima start --cpu 2 --memory 4`
+  - for big infrastructures: `colima start --cpu 2 --memory 6`
+4) `brew services start colima` to automatically start colima on startup
+5) Exit your terminal, open a new one
+6) You can now use docker CLI
+
+
+{{% alert color="info" %}}
+If you get an error at rosetta startup, run `colima delete` and try again (the disk format is not compatible). Settings will be lost.
+{{% /alert %}}

content/docs/guides/contribute/install-docker.fr.md

@@ -0,0 +1,50 @@
+---
+title: "Installer docker"
+linkTitle: "Installer docker"
+weight: 15
+---
+
+Peu importe votre système d'exploitation, docker requiert linux pour fonctionner.
+Lorsqu'utilisé sous un autre système d'exploitation, docker a besoin de machines
+virtuelles linux pour build et exécuter des images.
+
+Il y a deux types d'installation docker :
+- docker engine est l'application en ligne de commande
+- docker desktop est une application graphique, qui gère aussi la virtualisation
+
+Voici nos suggestions :
+- Si vous êtes sous linux, installez docker engine [via votre gestionnaire de packet](https://docs.docker.com/engine/install/#supported-platforms)
+- Si vous êtes sous MacOS / Windows, installez [docker desktop](https://www.docker.com/products/docker-desktop/) si vous y êtes autorisés
+- Si vous êtes sous windows, et voulez faire fonctionner docker sous WSL, ou ne pouvez pas utiliser docker desktop, suivez le [guide docker sous WSL](#docker-sous-wsl)
+- Si vous êtes sous MacOS, et vous ne pouvez pas utiliser docker desktop, suivez le [guide colima pour MacOS](#macos-colima)
+
+
+## Docker sous WSL
+
+Cette option d'installation est très utile, car elle permet de disposer d'une installation tout à fait normale de docker engine Linux à l'intérieur de WSL, qui reste accessible depuis Windows.
+
+- [Installez WSL](https://learn.microsoft.com/fr-fr/windows/wsl/install) (Si vous avez une vieille version de WSL, lancez `wsl --upgrade`)
+- Obtenez une image WSL depuis le store microsoft (par exemple, debian or ubuntu)
+- [Activez le support systemd depuis la VM WSL](https://learn.microsoft.com/fr-fr/windows/wsl/systemd)
+- Suivez le [tutoriel d'installation docker engine pour votre distribution WSL](https://docs.docker.com/engine/install/#supported-platforms)
+- Si vous avez docker desktop installé, vous pouvez [le configurer pour qu'il utilise WSL](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers)
+
+
+## MacOS colima
+
+Cette procédure permet d'installer docker sans passer par docker desktop. Elle utilise colima comme solution de virtualisation.
+
+1) [Installez homebrew](https://brew.sh/)
+2) `brew install docker docker-compose colima`
+3) [Configurez colima](https://github.com/abiosoft/colima?tab=readme-ov-file#customizing-the-vm) :
+  - pour des macbooks apple silicon (M1/M2) : `colima start --cpu 2 --memory 6 --arch aarch64 --vm-type=vz --vz-rosetta --mount-type=virtiofs`
+  - pour de petites infrastructures: `colima start --cpu 2 --memory 4`
+  - pour de grosses infrastructures: `colima start --cpu 2 --memory 6`
+4) `brew services start colima` pour lancer automatiquement colima au démarrage
+5) Quittez votre terminal, ouvrez-en un nouveau
+6) Vous pouvez maintenant utiliser docker CLI
+
+
+{{% alert color="info" %}}
+En cas d'erreur au démarrage avec Rosetta 2, lancez `colima delete` et réessayez (le format de disque n'est pas compatible). Les paramètres seront perdus.
+{{% /alert %}}

content/docs/guides/contribute/license-and-set-up.en.md

@@ -28,13 +28,18 @@ Most OSRD developers use Linux (incl. [WSL](https://learn.microsoft.com/en-us/wi
 
 ### Launch the application
 
-Thanks to `docker`, one can easily compile, configure, and run all services after making a change. One can also start only a subset of the services.
-
-- Install `docker`. [^package-manager] [^docker-desktop]
+Docker is a tool which greatly reduces the amount of setup required to work on OSRD:
+- download the latest development build: `docker compose pull`
+- start OSRD: `docker compose up`
+- build and start OSRD: `docker compose up --build`
+- review a PR using CI built images: `TAG=pr-XXXXX docker compose up --no-build --pull always`
+
+To get started:
+- [Install `docker`]({{< ref "install-docker">}})
 - Follow [OSRD's README](https://github.com/osrd-project/osrd#getting-started).
 
-[^package-manager]: Under Linux, follow installations steps for your distribution on [Docker's documentation](https://docs.docker.com/engine/install/)
-[^git-bash]: Under Windows, open `Git Bash`
-[^docker-desktop]: Under Windows/[WSL](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers), [Docker Desktop](https://www.docker.com/products/docker-desktop/) is recommended
-
 *[Continue towards code contribution ‣]({{< ref "contribute-code">}})*
+
+
+[^package-manager]: Under Linux, use the package manager (such as `apt`)
+[^git-bash]: Under Windows, open `Git Bash`

content/docs/guides/contribute/license-and-set-up.fr.md

@@ -28,13 +28,19 @@ La plupart des développeurs OSRD utilisent Linux  (y compris [WSL](https://lear
 
 ### Lancer l'application
 
-Grâce à `docker`, on peut facilement compiler, configurer, et lancer les différents composants après un changement. On peut aussi choisir de lancer seulement une partie des composants.
+Docker est un outil qui réduit considérablement la préparation nécessaire pour travailler sur OSRD:
+- télécharger le dernier build de développement : `docker compose pull`
+- démarrer OSRD : `docker compose up`
+- compiler et démarrer OSRD: `docker compose up --build`
+- review une PR avec les images compilées par la CI: `TAG=pr-XXXXX docker compose up --no-build --pull always`
 
-- Installer `docker` [^package-manager] [^docker-desktop].
-- Suivre le [README d'OSRD](https://github.com/osrd-project/osrd#getting-started).
 
-[^package-manager]: Sous Linux, suivez les guides pour votre distribution dans la [documentation de Docker](https://docs.docker.com/engine/install/)
-[^git-bash]: Sous Windows, ouvrez `Git Bash`
-[^docker-desktop]: Sous Windows/[WSL](https://learn.microsoft.com/fr-fr/windows/wsl/tutorials/wsl-containers), [Docker Desktop](https://www.docker.com/products/docker-desktop/) est recommandé
+Pour commencer :
+- [Installer `docker`]({{< ref "install-docker">}})
+- Suivre le [README d'OSRD](https://github.com/osrd-project/osrd#getting-started).
 
 *[Continuer vers la contribution au code ‣]({{< ref "contribute-code">}})*
+
+
+[^package-manager]: Sous Linux, utilisez le gestionnaire de packet (comme `apt`)
+[^git-bash]: Sous Windows, ouvrez `Git Bash`