Documentation for self-hosting with docker compose (#855)

## Purpose

Make self hosting of Docs easier with an example of a deployment
procedure with docker compose and document how to configure Docs.

While https://github.com/suitenumerique/docs/pull/583 propose an easy
way to deploy Docs with docker and Make, here we describe more in
details the various steps and requirements to deploy Docs.

## Proposal

- [x] example to deploy and configure keycloak
- [x] example to deploy and configure minio
- [x] example to configure proxy and certs
- [x] example to deploy and configure Docs

## Improvements
- [x] Rephrase description of environment variables and categorize
- [x] Use template for nginx conf  

Fixes https://github.com/suitenumerique/docs/issues/561
Supersedes https://github.com/suitenumerique/docs/pull/583

 A one liner quick start could be a nice addition:
- [ ] merge all services in a single compose
- [ ] scripts to generate secrets

Signed-off-by: unteem <timothee@indie.host>

docs/examples/compose/compose.yaml

@@ -0,0 +1,78 @@
+services:
+  postgresql:
+    image: postgres:16
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
+      interval: 1s
+      timeout: 2s
+      retries: 300
+    env_file:
+    - env.d/postgresql
+    - env.d/common
+    environment:
+    - PGDATA=/var/lib/postgresql/data/pgdata
+    volumes:
+    - ./data/databases/backend:/var/lib/postgresql/data/pgdata
+
+  redis:
+    image: redis:8
+
+  backend:
+    image: lasuite/impress-backend:latest
+    user: ${DOCKER_USER:-1000}
+    restart: always
+    environment:
+    - DJANGO_CONFIGURATION=Production
+    env_file:
+    - env.d/common
+    - env.d/backend
+    - env.d/yprovider
+    - env.d/postgresql
+    healthcheck:
+      test: ["CMD", "python", "manage.py", "check"]
+      interval: 15s
+      timeout: 30s
+      retries: 20
+      start_period: 10s
+    depends_on:
+      postgresql:
+        condition: service_healthy
+        restart: true
+      redis:
+        condition: service_started
+
+  y-provider:
+    image: lasuite/impress-y-provider:latest
+    user: ${DOCKER_USER:-1000}
+    env_file:
+    - env.d/common
+    - env.d/yprovider
+
+  frontend:
+    image: lasuite/impress-frontend:latest
+    user: "101"
+    entrypoint:
+    - /docker-entrypoint.sh
+    command: ["nginx", "-g", "daemon off;"]
+    env_file:
+    - env.d/common
+    # Uncomment and set your values if using our nginx proxy example
+    #environment:
+    # - VIRTUAL_HOST=${DOCS_HOST} # used by nginx proxy 
+    # - VIRTUAL_PORT=8083 # used by nginx proxy
+    # - LETSENCRYPT_HOST=${DOCS_HOST} # used by lets encrypt to generate TLS certificate
+    volumes:
+    - ./default.conf.template:/etc/nginx/templates/docs.conf.template
+    depends_on:
+      backend:
+        condition: service_healthy
+
+# Uncomment if using our nginx proxy example
+#    networks:
+#    - proxy-tier
+#    - default
+
+# Uncomment if using our nginx proxy example
+#networks:
+#  proxy-tier:
+#    external: true

docs/examples/compose/keycloak/README.md

@@ -0,0 +1,88 @@
+# Deploy and Configure Keycloak for Docs
+
+## Installation
+
+> \[!CAUTION\]
+> We provide those instructions as an example, for production environments, you should follow the [official documentation](https://www.keycloak.org/documentation).
+
+### Step 1: Prepare your working environment:
+
+```bash
+mkdir keycloak
+curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/keycloak/compose.yaml
+curl -o env.d/kc_postgresql https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/kc_postgresql
+curl -o env.d/keycloak https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/keycloak
+```
+
+### Step 2:. Update `env.d/` files
+
+The following variables need to be updated with your own values, others can be left as is:
+
+```env
+POSTGRES_PASSWORD=<generate postgres password>
+KC_HOSTNAME=https://id.yourdomain.tld # Change with your own URL
+KC_BOOTSTRAP_ADMIN_PASSWORD=<generate your password>
+```
+
+### Step 3: Expose keycloak instance on https
+
+> \[!NOTE\]
+> You can skip this section if you already have your own setup.
+
+To access your Keycloak instance on the public network, it needs to be exposed on a domain with SSL termination. You can use our [example with nginx proxy and Let's Encrypt companion](../nginx-proxy/README.md) for automated creation/renewal of certificates using [acme.sh](http://acme.sh).
+
+If following our example, uncomment the environment and network sections in compose file and update it with your values.
+
+```yaml
+version: '3'
+services:
+  keycloak:
+   ...
+    # Uncomment and set your values if using our nginx proxy example
+    # environment:
+    # - VIRTUAL_HOST=id.yourdomain.tld # used by nginx proxy 
+    # - VIRTUAL_PORT=8080 # used by nginx proxy
+    # - LETSENCRYPT_HOST=id.yourdomain.tld # used by lets encrypt to generate TLS certificate
+   ...
+# Uncomment if using our nginx proxy example
+#    networks:
+#    - proxy-tier
+#    - default
+
+# Uncomment if using our nginx proxy example
+#networks:
+#  proxy-tier:
+#    external: true
+```
+
+### Step 4: Start the service
+
+```bash
+`docker compose up -d`
+```
+
+Your keycloak instance is now available on https://doc.yourdomain.tld
+
+## Creating an OIDC Client for Docs Application
+
+### Step 1: Create a New Realm
+
+1. Log in to the Keycloak administration console.
+2. Navigate to the realm tab and click on the "Create realm" button.
+3. Enter the name of the realm  - `docs`.
+4. Click "Create".
+
+#### Step 2: Create a New Client
+
+1. Navigate to the "Clients" tab.
+2. Click on the "Create client" button.
+3. Enter the client ID - e.g. `docs`.
+4. Enable "Client authentication" option.
+6. Set the "Valid redirect URIs" to the URL of your docs application suffixed with `/*` - e.g., "https://docs.example.com/*".
+1. Set the "Web Origins" to the URL of your docs application - e.g. `https://docs.example.com`.
+1. Click "Save".
+
+#### Step 3: Get Client Credentials
+
+1. Go to the "Credentials" tab.
+2. Copy the client ID (`docs` in this example) and the client secret.

docs/examples/compose/keycloak/compose.yaml

@@ -0,0 +1,36 @@
+services:
+  kc_postgresql:
+    image: postgres:16
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
+      interval: 1s
+      timeout: 2s
+      retries: 300
+    env_file:
+    - env.d/kc_postgresql
+    volumes:
+    - ./data/keycloak:/var/lib/postgresql/data/pgdata
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1.3
+    command: ["start"]
+    env_file:
+    - env.d/kc_postgresql
+    - env.d/keycloak
+    # Uncomment and set your values if using our nginx proxy example
+    # environment:
+    # - VIRTUAL_HOST=id.yourdomain.tld # used by nginx proxy 
+    # - VIRTUAL_PORT=8080 # used by nginx proxy
+    # - LETSENCRYPT_HOST=id.yourdomain.tld # used by lets encrypt to generate TLS certificate
+    depends_on:
+      kc_postgresql::
+        condition: service_healthy
+        restart: true
+# Uncomment if using our nginx proxy example
+#    networks:
+#    - proxy-tier
+#    - default
+#
+#networks:
+#  proxy-tier:
+#    external: true

docs/examples/compose/minio/README.md

@@ -0,0 +1,103 @@
+# Deploy and Configure Minio for Docs
+
+## Installation
+
+> \[!CAUTION\]
+> We provide those instructions as an example, it should not be run in production. For production environments, deploy MinIO [in a Multi-Node Multi-Drive (Distributed)](https://min.io/docs/minio/linux/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.html#minio-mnmd) topology
+
+### Step 1: Prepare your working environment:
+
+```bash
+mkdir minio
+curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/minio/compose.yaml 
+```
+
+### Step 2:. Update compose file with your own values
+
+```yaml
+version: '3'
+services:
+  minio:
+   ...
+    environment:
+    - MINIO_ROOT_USER=<Set minio root username>
+    - MINIO_ROOT_PASSWORD=<Set minio root password>
+```
+
+### Step 3: Expose MinIO instance
+
+#### Option 1: Internal network
+
+You may not need to expose your MinIO instance to the public if only services hosted on the same private network need to access to your MinIO instance.
+
+You should create a docker network that will be shared between those services
+
+```bash
+docker network create storage-tier
+```
+
+#### Option 2: Public network
+
+If you want to expose your MinIO instance to the public, it needs to be exposed on a domain with SSL termination. You can use our [example](../nginx-proxy/README.md) with an nginx proxy and Let's Encrypt companion for automated creation/renewal of Let's Encrypt certificates using [acme.sh](http://acme.sh).
+
+If following our example, uncomment the environment and network sections in compose file and update it with your values.
+
+```yaml
+version: '3'
+services:
+   docs:
+   ...
+  minio:
+   ...
+    environment:
+   ...
+    # - VIRTUAL_HOST=storage.yourdomain.tld # used by nginx proxy 
+    # - VIRTUAL_PORT=9000 # used by nginx proxy
+    # - LETSENCRYPT_HOST=storage.yourdomain.tld # used by lets encrypt to generate TLS certificate
+   ...
+# Uncomment if using our nginx proxy example
+#    networks:
+#    - proxy-tier
+#    - default
+
+# Uncomment if using our nginx proxy example
+#networks:
+#  proxy-tier:
+#    external: true
+```
+
+In this example we are only exposing MinIO API service. Follow the official documentation to configure Minio WebUI.
+
+### Step 4: Start the service
+
+```bash
+`docker compose up -d`
+```
+
+Your minio instance is now available on https://storage.yourdomain.tld
+
+## Creating a user and bucket for your Docs instance
+
+### Installing mc
+
+Follow the [official documentation](https://min.io/docs/minio/linux/reference/minio-mc.html#install-mc) to install mc
+
+### Step 1: Configure `mc` to connect to your MinIO Server with your root user
+
+```shellscript
+mc alias set minio <MINIO_SERVER_URL> <MINIO_ROOT_USER> <MINIO_ROOT_PASSWORD>
+```
+
+Replace the values with those you have set in the previous steps
+
+### Step 2: Create a new bucket with versioning enabled
+
+```shellscript
+mc mb --with-versioning minio/<your-bucket-name>
+```
+
+Replace `your-bucket-name` with the desired name for your bucket e.g. `docs-media-storage`
+
+### Additional notes:
+
+For increased security you should create a dedicated user with `readwrite` access to the Bucket. In the following example we will use MinIO root user.

docs/examples/compose/minio/compose.yaml

@@ -0,0 +1,27 @@
+services:
+  minio:
+    image: minio/minio
+    environment:
+    - MINIO_ROOT_USER=<set minio root username>
+    - MINIO_ROOT_PASSWORD=<set minio root password>
+    # Uncomment and set your values if using our nginx proxy example
+    # - VIRTUAL_HOST=storage.yourdomain.tld # used by nginx proxy 
+    # - VIRTUAL_PORT=9000 # used by nginx proxy
+    # - LETSENCRYPT_HOST=storage.yourdomain.tld # used by lets encrypt to generate TLS certificate
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 1s
+      timeout: 20s
+      retries: 300
+    entrypoint: ""
+    command: minio server /data
+    volumes:
+    - ./data/minio:/data
+# Uncomment if using our nginx proxy example
+#    networks:
+#    - proxy-tier
+
+# Uncomment if using our nginx proxy example
+#networks:
+#  proxy-tier:
+#    external: true

docs/examples/compose/nginx-proxy/README.md

@@ -0,0 +1,39 @@
+# Nginx proxy with automatic SSL certificates
+
+> \[!CAUTION\]
+> We provide those instructions as an example, for extended development or production environments, you should follow the [official documentation](https://github.com/nginx-proxy/acme-companion/tree/main/docs).
+
+Nginx-proxy sets up a container running nginx and docker-gen. docker-gen generates reverse proxy configs for nginx and reloads nginx when containers are started and stopped.
+
+Acme-companion is a lightweight companion container for nginx-proxy. It handles the automated creation, renewal and use of SSL certificates for proxied Docker containers through the ACME protocol.
+
+## Installation
+
+### Step 1: Prepare your working environment:
+
+```bash
+mkdir nginx-proxy
+curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/nginx-proxy/compose.yaml
+```
+
+### Step 2: Edit `DEFAULT_EMAIL` in the compose file.
+
+Albeit optional, it is recommended to provide a valid default email address through the `DEFAULT_EMAIL` environment variable, so that Let's Encrypt can warn you about expiring certificates and allow you to recover your account.
+
+### Step 3: Create docker network
+
+Containers need share the same network for auto-discovery.
+
+```bash
+docker network create proxy-tier
+```
+
+### Step 4: Start service
+
+```bash
+docker compose up -d
+```
+
+## Usage
+
+Once both nginx-proxy and acme-companion containers are up and running, start any container you want proxied with environment variables `VIRTUAL_HOST` and `LETSENCRYPT_HOST` both set to the domain(s) your proxied container is going to use.

docs/examples/compose/nginx-proxy/compose.yaml

@@ -0,0 +1,36 @@
+services:
+  nginx-proxy:
+    image: nginxproxy/nginx-proxy
+    container_name: nginx-proxy
+    ports:
+    - "80:80"
+    - "443:443"
+    volumes:
+    - html:/usr/share/nginx/html
+    - certs:/etc/nginx/certs:ro
+    - /var/run/docker.sock:/tmp/docker.sock:ro
+    networks:
+    - proxy-tier
+
+  acme-companion:
+    image: nginxproxy/acme-companion
+    container_name: nginx-proxy-acme
+    environment:
+    - DEFAULT_EMAIL=mail@yourdomain.tld
+    volumes_from:
+    - nginx-proxy
+    volumes:
+    - certs:/etc/nginx/certs:rw
+    - acme:/etc/acme.sh
+    - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+    - proxy-tier
+
+networks:
+  proxy-tier:
+    external: true
+
+volumes:
+  html:
+  certs:
+  acme: