♻️ (deploy) harmonize prod deployment layout under deploy/

.github/workflows/helmfile-linter.yaml

@@ -21,7 +21,7 @@ jobs:
       shell: bash
       run: |
         set -e
-        HELMFILE=src/helm/helmfile.yaml.gotmpl
+        HELMFILE=deploy/kubernetes/helm/helmfile.yaml.gotmpl
         environments=$(awk 'BEGIN {in_env=0} /^environments:/ {in_env=1; next} /^---/ {in_env=0} in_env && /^  [^ ]/ {gsub(/^  /,""); gsub(/:.*$/,""); print}' "$HELMFILE")
         for env in $environments; do
           echo "################### $env lint ###################"

.github/workflows/release-helm-chart.yaml

@@ -4,7 +4,7 @@ run-name: Release Chart
 on:
   push:
     paths:
-      - src/helm/impress/**
+      - deploy/kubernetes/helm/impress/**
 
 jobs:
   release:
@@ -20,7 +20,7 @@ jobs:
           fetch-depth: 0
 
       - name: Cleanup
-        run: rm -rf ./src/helm/extra
+        run: rm -rf ./deploy/kubernetes/helm/extra
 
       - name: Install Helm
         uses: azure/setup-helm@dda3372f752e03dde6b3237bc9431cdc2f7a02a2 # v5
@@ -30,5 +30,5 @@ jobs:
       - name: Publish Helm charts
         uses: numerique-gouv/helm-gh-pages@2cf477ae49d7c70037ceb1685803f4f7bad9b981 # add-overwrite-option
         with:
-          charts_dir: ./src/helm
+          charts_dir: ./deploy/kubernetes/helm
           token: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -6,6 +6,8 @@ and this project adheres to
 
 ## [Unreleased]
 
+- ♻️ (deploy) harmonize prod deployment layout under deploy/ #2425
+
 ### Added
 
 - ✨(frontend) add top parent on sub docs search #1952

Procfile

@@ -1,2 +1,2 @@
-web: bin/buildpack_start.sh
+web: deploy/paas/buildpack_start.sh
 postdeploy: python manage.py migrate

bin/Tiltfile

@@ -46,7 +46,7 @@ k8s_resource('impress-docs-backend-migrate', resource_deps=['dev-backend-postgre
 k8s_resource('impress-docs-backend-createsuperuser', resource_deps=['impress-docs-backend-migrate'])
 k8s_resource('dev-backend-keycloak', resource_deps=['dev-backend-keycloak-pg'])
 k8s_resource('impress-docs-backend', resource_deps=['impress-docs-backend-migrate', 'dev-backend-redis', 'dev-backend-keycloak', 'dev-backend-postgres', 'dev-backend-minio:statefulset'])
-k8s_yaml(local('cd ../src/helm && helmfile -n impress -e dev template .'))
+k8s_yaml(local('cd ../deploy/kubernetes/helm && helmfile -n impress -e dev template .'))
 
 migration = '''
 set -eu

deploy/docker/README.md

@@ -0,0 +1,43 @@
+# Docs — Docker Compose deployment
+
+Prod-oriented Docker Compose layout for [Docs](https://github.com/suitenumerique/docs).
+
+> The root `compose.yml` of the repository is the **development** stack. Use the files in this folder to deploy Docs in production.
+
+## Layout
+
+```
+deploy/docker/
+├── compose.yml              # Main production compose file
+├── env.d/                   # (you provide) postgres / backend / yprovider / common env files
+└── examples/
+    ├── keycloak/            # Sample OIDC provider
+    ├── minio/               # Sample S3-compatible object storage
+    └── nginx-proxy/         # Sample reverse proxy with Let's Encrypt
+```
+
+## Getting started
+
+See the [installation walkthrough](../../docs/installation/compose.md) — it covers env files, OIDC, S3, Postgres, Redis, mail and reverse-proxy setup end to end.
+
+Quick setup:
+
+```bash
+mkdir -p docs/env.d && cd docs
+
+# Fetch the compose file and example env files
+curl -o compose.yml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/deploy/docker/compose.yml
+curl -o env.d/common     https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/common
+curl -o env.d/backend    https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/backend
+curl -o env.d/yprovider  https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/yprovider
+curl -o env.d/postgresql https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/postgresql
+
+# Pin to a tagged release before going to production
+docker compose up -d
+docker compose run --rm backend python manage.py migrate
+```
+
+## Other deployments
+
+* Kubernetes/Helm: see [`deploy/kubernetes/`](../kubernetes/).
+* PaaS (Scalingo, Clever Cloud, …): see [`deploy/paas/`](../paas/).

docs/examples/compose/keycloak/README.md → deploy/docker/examples/keycloak/README.md

@@ -9,7 +9,7 @@
 
 ```bash
 mkdir keycloak
-curl -o keycloak/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/keycloak/compose.yaml
+curl -o keycloak/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/deploy/docker/examples/keycloak/compose.yaml
 curl -o keycloak/env.d/kc_postgresql https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/kc_postgresql
 curl -o keycloak/env.d/keycloak https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/keycloak
 ```

docs/examples/compose/minio/README.md → deploy/docker/examples/minio/README.md

@@ -9,7 +9,7 @@
 
 ```bash
 mkdir minio
-curl -o minio/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/minio/compose.yaml 
+curl -o minio/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/deploy/docker/examples/minio/compose.yaml 
 ```
 
 ### Step 2:. Update compose file with your own values

docs/examples/compose/nginx-proxy/README.md → deploy/docker/examples/nginx-proxy/README.md

@@ -13,7 +13,7 @@ Acme-companion is a lightweight companion container for nginx-proxy. It handles
 
 ```bash
 mkdir nginx-proxy
-curl -o nginx-proxy/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/nginx-proxy/compose.yaml
+curl -o nginx-proxy/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/deploy/docker/examples/nginx-proxy/compose.yaml
 ```
 
 ### Step 2: Edit `DEFAULT_EMAIL` in the compose file.

deploy/paas/README.md

@@ -0,0 +1,31 @@
+# Docs — PaaS deployment
+
+Buildpack scripts and nginx template for deploying [Docs](https://github.com/suitenumerique/docs) on a PaaS (Scalingo, Clever Cloud, …).
+
+## Layout
+
+```
+deploy/paas/
+├── buildpack_postcompile.sh   # Build-time: cleanup unused files to reduce slug size
+├── buildpack_postfrontend.sh  # Build-time: assemble frontend/backend/nginx into slug
+├── buildpack_start.sh         # Runtime: starts uvicorn + y-provider + nginx
+└── servers.conf.erb           # Nginx routing template (ERB → consumed by buildpack)
+```
+
+The root `Procfile` references `deploy/paas/buildpack_start.sh` for the `web` process.
+
+## Getting started
+
+See the [Scalingo walkthrough](../../docs/installation/scalingo.md) — it covers the full env-var setup (buildpack URL, OIDC, S3, theme customization, etc.).
+
+The two build-time hooks are wired via the [La Suite buildpack](https://github.com/suitenumerique/buildpack) env vars:
+
+```bash
+scalingo env-set LASUITE_SCRIPT_POSTCOMPILE="deploy/paas/buildpack_postcompile.sh"
+scalingo env-set LASUITE_SCRIPT_POSTFRONTEND="deploy/paas/buildpack_postfrontend.sh"
+```
+
+## Other deployments
+
+* Docker Compose: see [`deploy/docker/`](../docker/).
+* Kubernetes/Helm: see [`deploy/kubernetes/`](../kubernetes/).

bin/buildpack_postfrontend.sh → deploy/paas/buildpack_postfrontend.sh

@@ -45,7 +45,7 @@ if [ -n "$THEME_CUSTOMIZATION_LOGO_URL" ]; then
 fi
 
 mv src/backend/* ./
-mv deploy/paas/* ./
+mv deploy/paas/servers.conf.erb ./
 
 # Inject custom theme JSON
 if [ -n "$THEME_CUSTOMIZATION_JSON" ]; then

docs/customization.md

@@ -89,6 +89,28 @@ Then, set the `FRONTEND_JS_URL` environment variable to the URL of your custom J
 
 ----
 
+## **Providing theme customization** ⚙️
+
+The theme customization configuration can be provided in two ways. Pick the one that fits your deployment:
+
+* **Inline JSON via env var (recommended for PaaS / Docker / Kubernetes)** — set `THEME_CUSTOMIZATION_JSON` to the JSON string itself. No file mount required.
+
+    ```shellscript
+    THEME_CUSTOMIZATION_JSON='{"header":{"icon":"https://..."}}'
+    ```
+
+* **Mounted JSON file** — set `THEME_CUSTOMIZATION_FILE_PATH` to the absolute path of a JSON file inside the container.
+
+    ```shellscript
+    THEME_CUSTOMIZATION_FILE_PATH=<path>
+    ```
+
+When both are set, `THEME_CUSTOMIZATION_JSON` is prioritized.
+
+The sections below describe the schema. Each example links to the reference JSON at `deploy/kubernetes/helm/env.d/dev/configuration/theme/demo.json`.
+
+----
+
 ## **Your Docs icon** 📝
 
 You can add your own Docs icon in the header from the theme customization file.
@@ -97,11 +119,13 @@ You can add your own Docs icon in the header from the theme customization file.
 
 ```shellscript
 THEME_CUSTOMIZATION_FILE_PATH=<path>
+# or
+THEME_CUSTOMIZATION_JSON=<inline JSON>
 ```
 
 ### Example of JSON
 
-You can activate it with the `header.icon` configuration: https://github.com/suitenumerique/docs/blob/main/src/helm/env.d/dev/configuration/theme/demo.json
+You can activate it with the `header.icon` configuration: https://github.com/suitenumerique/docs/blob/main/deploy/kubernetes/helm/env.d/dev/configuration/theme/demo.json
 
 This configuration is optional. If not set, the default icon will be used.
 
@@ -119,7 +143,7 @@ THEME_CUSTOMIZATION_FILE_PATH=<path>
 
 ### Example of JSON
 
-The json must follow some rules: https://github.com/suitenumerique/docs/blob/main/src/helm/env.d/dev/configuration/theme/demo.json
+The json must follow some rules: https://github.com/suitenumerique/docs/blob/main/deploy/kubernetes/helm/env.d/dev/configuration/theme/demo.json
 
 `footer.default` is the fallback if the language is not supported.
 
@@ -142,7 +166,7 @@ THEME_CUSTOMIZATION_FILE_PATH=<path>
 
 ### Example of JSON
 
-The json must follow some rules: https://github.com/suitenumerique/docs/blob/main/src/helm/env.d/dev/configuration/theme/demo.json
+The json must follow some rules: https://github.com/suitenumerique/docs/blob/main/deploy/kubernetes/helm/env.d/dev/configuration/theme/demo.json
 
 ----
 
@@ -168,7 +192,7 @@ See: [LaGaufreV2Props](https://github.com/suitenumerique/ui-kit/blob/main/src/co
 
 ### Complete Example
 
-From the theme customization file: https://github.com/suitenumerique/docs/blob/main/src/helm/env.d/dev/configuration/theme/demo.json
+From the theme customization file: https://github.com/suitenumerique/docs/blob/main/deploy/kubernetes/helm/env.d/dev/configuration/theme/demo.json
 
 ### Behavior
 

docs/env.md

@@ -138,6 +138,7 @@ These are the environment variables you can set for the `impress-backend` contai
 | STORAGES_STATICFILES_BACKEND                    |                                                                                                                                                                            | whitenoise.storage.CompressedManifestStaticFilesStorage                 |
 | THEME_CUSTOMIZATION_CACHE_TIMEOUT               | Cache duration for the customization settings                                                                                                                              | 86400                                                                   |
 | THEME_CUSTOMIZATION_FILE_PATH                   | Full path to the file customizing the theme. An example is provided in src/backend/impress/configuration/theme/default.json                                                | BASE_DIR/impress/configuration/theme/default.json                       |
+| THEME_CUSTOMIZATION_JSON                        | Inline JSON string customizing the theme. Takes precedence over `THEME_CUSTOMIZATION_FILE_PATH` when set. Convenient for PaaS / Docker / Kubernetes deployments.            |                                                                         |
 | TRASHBIN_CUTOFF_DAYS                            | Trashbin cutoff                                                                                                                                                            | 30                                                                      |
 | TREEBEARD_PATH_COMPUTE_RETRY_MAX_ATTEMPTS       | Number of attempts to create a document before failing.                                                                                                                    | 10                                                                      |
 | USER_OIDC_ESSENTIAL_CLAIMS                      | Essential claims in OIDC token                                                                                                                                             | []                                                                      |

docs/installation/compose.md

@@ -6,10 +6,10 @@ We provide a sample configuration for running Docs using Docker Compose. Please
 
 - A modern version of Docker and its Compose plugin.
 - A domain name and DNS configured to your server.
-- An Identity Provider that supports OpenID Connect protocol - we provide [an example to deploy Keycloak](../examples/compose/keycloak/README.md).
-- An Object Storage that implements S3 API - we provide [an example to deploy Minio](../examples/compose/minio/README.md).
-- A Postgresql database - we provide [an example in the compose file](../examples/compose/compose.yaml).
-- A Redis database - we provide [an example in the compose file](../examples/compose/compose.yaml).
+- An Identity Provider that supports OpenID Connect protocol - we provide [an example to deploy Keycloak](../../deploy/docker/examples/keycloak/README.md).
+- An Object Storage that implements S3 API - we provide [an example to deploy Minio](../../deploy/docker/examples/minio/README.md).
+- A Postgresql database - we provide [an example in the compose file](../../deploy/docker/compose.yml).
+- A Redis database - we provide [an example in the compose file](../../deploy/docker/compose.yml).
 
 ## Software Requirements
 
@@ -32,7 +32,7 @@ For older versions of Docker Engine that do not include Docker Compose:
 ```bash
 mkdir -p docs/env.d
 cd docs
-curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/compose.yaml
+curl -o compose.yml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/deploy/docker/compose.yml
 curl -o env.d/common https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/common
 curl -o env.d/backend https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/backend
 curl -o env.d/yprovider https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/yprovider
@@ -61,7 +61,7 @@ In this example, we assume the following services:
 
 Authentication in Docs is managed through Open ID Connect protocol. A functional Identity Provider implementing this protocol is required.
 
-For guidance, refer to our [Keycloak deployment example](../examples/compose/keycloak/README.md).
+For guidance, refer to our [Keycloak deployment example](../../deploy/docker/examples/keycloak/README.md).
 
 If using Keycloak as your Identity Provider, set `OIDC_RP_CLIENT_ID` and `OIDC_RP_CLIENT_SECRET` variables with those of the OIDC client created for Docs. By default we have set `docs` as the realm name, if you have named your realm differently, update the value `REALM_NAME` in `env.d/common`
 
@@ -71,7 +71,7 @@ For others OIDC providers, update the variables in `env.d/backend`.
 
 Files and media are stored in an Object Store that supports the S3 API.
 
-For guidance, refer to our [Minio deployment example](../examples/compose/minio/README.md).
+For guidance, refer to our [Minio deployment example](../../deploy/docker/examples/minio/README.md).
 
 Set `AWS_S3_ACCESS_KEY_ID` and `AWS_S3_SECRET_ACCESS_KEY` with the credentials of a user with `readwrite` access to the bucket created for Docs.
 
@@ -147,7 +147,7 @@ AI_MODEL=<model used> e.g. llama
 
 ### Frontend theme
 
-You can [customize your Docs instance](../theming.md) with your own theme and custom css.
+You can [customize your Docs instance](../customization.md) with your own theme and custom css.
 
 The following environment variables must be set in `env.d/backend`:
 
@@ -163,7 +163,7 @@ FRONTEND_CSS_URL=https://storage.yourdomain.tld/themes/custom.css # custom css
 
 If you have your own certificates and proxy setup, you can skip this part.
 
-You can follow our [nginx proxy example](../examples/compose/nginx-proxy/README.md) with automatic generation and renewal of certificate with Let's Encrypt. 
+You can follow our [nginx proxy example](../../deploy/docker/examples/nginx-proxy/README.md) with automatic generation and renewal of certificate with Let's Encrypt. 
 
 You will need to uncomment the environment and network sections in compose file and update it with your values.
 

docs/installation/scalingo.md

@@ -39,8 +39,8 @@ scalingo env-set LASUITE_APP_NAME="docs"
 scalingo env-set LASUITE_BACKEND_DIR="src/backend/"
 scalingo env-set LASUITE_FRONTEND_DIR="src/frontend/"
 scalingo env-set LASUITE_NGINX_DIR="."
-scalingo env-set LASUITE_SCRIPT_POSTCOMPILE="bin/buildpack_postcompile.sh"
-scalingo env-set LASUITE_SCRIPT_POSTFRONTEND="bin/buildpack_postfrontend.sh"
+scalingo env-set LASUITE_SCRIPT_POSTCOMPILE="deploy/paas/buildpack_postcompile.sh"
+scalingo env-set LASUITE_SCRIPT_POSTFRONTEND="deploy/paas/buildpack_postfrontend.sh"
 ```
 
 ### Database and Cache
@@ -237,12 +237,12 @@ On Scalingo, the application runs as follows:
 
 1. The buildpack compiles the frontend (Next.js static export)
 2. The buildpack compiles the backend (Python dependencies)
-3. `bin/buildpack_postcompile.sh` runs to clean up unused files and reduce slug size
-4. `bin/buildpack_postfrontend.sh` moves the frontend build to `build/frontend-out`, downloads custom logos, injects the custom theme, and prepares the deployment structure
+3. `deploy/paas/buildpack_postcompile.sh` runs to clean up unused files and reduce slug size
+4. `deploy/paas/buildpack_postfrontend.sh` moves the frontend build to `build/frontend-out`, downloads custom logos, injects the custom theme, and prepares the deployment structure
 
 ### Runtime
 
-The `bin/buildpack_start.sh` script starts three processes:
+The `deploy/paas/buildpack_start.sh` script starts three processes:
 
 - **Nginx** serves static files and proxies requests to the backend
 - **uvicorn** runs the Django ASGI application on port 8000

docs/release.md

@@ -7,7 +7,7 @@ Whenever we are cooking a new release (e.g. `4.18.1`) we should follow a standar
 
        - for backend, update the version number by hand in `pyproject.toml`,
        - for each projects (`src/frontend`, `src/frontend/apps/*`, `src/frontend/packages/*`, `src/mail`), run `yarn version --new-version --no-git-tag-version 4.18.1` in their directory. This will update their `package.json` for you,
-       - for Helm, update Docker image tag in files located at `src/helm/env.d` for both `preprod` and `production` environments:
+       - for Helm, update Docker image tag in files located at `deploy/kubernetes/helm/env.d` for both `preprod` and `production` environments:
 
          ```yaml
          image:

src/backend/core/api/viewsets.py

@@ -3102,6 +3102,25 @@ def get(self, request):
         return drf.response.Response(dict_settings)
 
     def _load_theme_customization(self):
+        if settings.THEME_CUSTOMIZATION_JSON:
+            cache_key = "theme_customization_env"
+            theme_customization = cache.get(cache_key, {})
+            if theme_customization:
+                return theme_customization
+
+            try:
+                theme_customization = json.loads(settings.THEME_CUSTOMIZATION_JSON)
+            except json.JSONDecodeError:
+                logger.error("THEME_CUSTOMIZATION_JSON is not a valid JSON")
+                return {}
+
+            cache.set(
+                cache_key,
+                theme_customization,
+                settings.THEME_CUSTOMIZATION_CACHE_TIMEOUT,
+            )
+            return theme_customization
+
         if not settings.THEME_CUSTOMIZATION_FILE_PATH:
             return {}