@intlayer/docs 9.5.6 → 9.5.7

package/docs/en/self_hosting.md

@@ -1,11 +1,13 @@
 ---
 createdAt: 2026-06-30
-updatedAt: 2026-08-23
+updatedAt: 2026-09-21
 title: Self-Hosting Intlayer
-description: Run a complete Intlayer instance on your own infrastructure with a single container. No Intlayer Cloud account required.
+description: "Run Intlayer on your own infrastructure: as a desktop app, a single all-in-one Docker container, or a scalable Docker Compose stack. No Intlayer Cloud account required."
 keywords:
   - Self-Hosting
   - Docker
+  - Docker Compose
+  - Desktop app
   - Intlayer
   - CMS
   - Installation
@@ -18,23 +20,78 @@ author: aymericzip
 
 # Self-Hosting Intlayer
 
-Intlayer can run on your own infrastructure. No Intlayer Cloud account required. A single all-in-one Docker image bundles the dashboard, the API, and the local datastores (Redis and MinIO) it needs, supervised by [s6-overlay](https://github.com/just-containers/s6-overlay).
+Intlayer can run on your own infrastructure, no Intlayer Cloud account required. Three setups are available, all driven by the same installer (`install.sh`, `install.ps1` on Windows, or `npx intlayer init infra`):
 
-One command installs everything:
+| Setup                 | What it is                                                                      | Pick it for                             |
+| --------------------- | ------------------------------------------------------------------------------- | --------------------------------------- |
+| **Desktop app**       | Native dashboard for macOS, Linux and Windows                                   | A local client, nothing to host         |
+| **All-in-one Docker** | Dashboard, API, MongoDB, Redis and MinIO in a **single container**              | Trials and small single-box installs    |
+| **Docker Compose**    | **One container per service**, each datastore replaceable by a managed offering | Production, scaling, managed datastores |
+
+## Table of Contents
+
+<TOC/>
+
+## Published images and packages
+
+| Artifact             | Docker Hub                                                                | GHCR mirror                                | Contents                                                                         |
+| -------------------- | ------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------- |
+| All-in-one container | [`intlayer/cms-all`](https://hub.docker.com/r/intlayer/cms-all)           | `ghcr.io/aymericzip/intlayer/cms-all`      | app + backend + MongoDB 8 + Redis + MinIO + Chromium                             |
+| Dashboard (frontend) | [`intlayer/cms-frontend`](https://hub.docker.com/r/intlayer/cms-frontend) | `ghcr.io/aymericzip/intlayer/cms-frontend` | TanStack Start dashboard on Bun                                                  |
+| API (backend)        | [`intlayer/cms-backend`](https://hub.docker.com/r/intlayer/cms-backend)   | `ghcr.io/aymericzip/intlayer/cms-backend`  | Fastify REST API on Bun + Chromium                                               |
+| Desktop app          | [GitHub releases](https://github.com/aymericzip/intlayer/releases/latest) | n/a                                        | `.dmg` (macOS), `.deb` / `.rpm` / `.AppImage` (Linux), `.exe` / `.msi` (Windows) |
+
+All three images are built from the same [`docker/selfhost/Dockerfile`](https://github.com/aymericzip/intlayer/tree/main/docker/selfhost) and published on every release. The Compose stack also pulls the official `mongo:8`, `redis:8-alpine` and `quay.io/minio/minio` images.
+
+## Setup
+
+The installer asks which setup you want, checks the prerequisites (offering to install Docker), writes the environment file with the secrets already generated, and pulls the images. It never starts anything on its own: the Docker modes need a mailer first, so it ends by printing the command to run. Re-running it is safe: an existing environment file is never overwritten, which makes it the upgrade path too.
+
+<Tabs group="mode">
+<Tab label="Desktop app" value="desktop">
+
+The Intlayer dashboard as a native application, built with Tauri. It signs in to the Intlayer Cloud (`https://app.intlayer.org`), so there is nothing to host. It is the right choice when you want a local client rather than a browser tab.
+
+### Install
+
+The installer downloads the package for your OS and CPU, then opens it (macOS), installs it (`dpkg` / `rpm` on Linux) or launches the setup wizard (Windows). You can also download it by hand from the [releases page](https://github.com/aymericzip/intlayer/releases/latest).
+
+<Tabs group="os">
+<Tab label="macOS / Linux" value="unix">
 
 ```sh
-curl -fsSL https://intlayer.org/install.sh | sh
+curl -fsSL https://intlayer.org/install.sh | sh -s -- --mode desktop
 ```
 
-The installer checks for Docker (offering to install it), writes an `intlayer.env` file with your secrets already generated, and pulls the image. It then asks you to fill in your credentials and prints the `docker run` command — see [Quick start](#quick-start).
+</Tab>
+<Tab label="Windows" value="windows">
 
-The only external dependency is **MongoDB**: the backend connects to a MongoDB **Atlas** cluster, which you provide. Everything else runs inside the container.
+In PowerShell:
 
-## Table of Contents
+```powershell
+$env:INTLAYER_MODE = "desktop"; irm https://intlayer.org/install.ps1 | iex
+```
 
-<TOC/>
+</Tab>
+<Tab label="Intlayer CLI" value="cli">
+
+```bash
+npx intlayer init infra --mode desktop
+```
 
-## Architecture
+</Tab>
+</Tabs>
+
+### Requirements
+
+- **Node.js**: the app embeds the dashboard's server and starts it with the machine's own `node` binary. Install it from [nodejs.org](https://nodejs.org) if the app does not start.
+
+> The published desktop build talks to the Intlayer Cloud backend. Pointing it at a self-hosted backend requires rebuilding the app with `VITE_BACKEND_URL` set to your API, see [Limitations](#limitations).
+
+</Tab>
+<Tab label="All-in-one Docker" value="docker">
+
+Everything runs inside the single `intlayer/cms-all` container, supervised by [s6-overlay](https://github.com/just-containers/s6-overlay), with every datastore persisted under one volume.
 
 ```
                 ┌─────────────────────────────┐
@@ -43,170 +100,410 @@ The only external dependency is **MongoDB**: the backend connects to a MongoDB *
                 ┌─────────────────────────────┐   │
                 │  backend (Fastify/Bun)  :3100│ ◀─┘
                 └──────────────┬──────────────┘
-          ┌──────────┬─────────┼───────────────────────┐
-          ▼          ▼         ▼                        ▼
-       redis:6379  minio:9000  Chromium            MongoDB Atlas
-       (bundled)   (S3 API)    (in-image)          (external, via DB_*)
-                   minio:9001
-                   (console)
+          ┌──────────┬─────────┼──────────────┐
+          ▼          ▼         ▼               ▼
+      mongo:27017  redis:6379  minio:9000   Chromium
+      /data/mongo  /data/redis /data/minio  (in-image)
+      (1-node RS)              minio:9001
 ```
 
-Chromium (used for Puppeteer screenshot generation) is bundled inside the image. No separate container is needed. Redis and MinIO run inside the container. MongoDB is **not** hosted by the image; the backend connects to your Atlas cluster over `mongodb+srv://`.
+| Service     | Host port(s)                  | Purpose                                                  |
+| ----------- | ----------------------------- | -------------------------------------------------------- |
+| **app**     | `3000`                        | Dashboard (CMS UI)                                       |
+| **backend** | `3100`                        | REST API (`/health` endpoint)                            |
+| **mongo**   | internal                      | MongoDB 8, single-node replica set `rs0`                 |
+| **redis**   | internal                      | Job queues (BullMQ) and caching                          |
+| **minio**   | `9000` (S3), `9001` (console) | S3-compatible object storage for avatars and screenshots |
 
-## Prerequisites
+Boot order is enforced by s6 dependencies (`mongod` → replica-set init, `minio` → bucket creation, then `backend`, then `app`), and services restart on exit, so the first boot recovers on its own.
 
-- **Docker** ≥ 24. The installer offers to install it for you if it is missing (via [get.docker.com](https://get.docker.com) on Linux, Homebrew on macOS).
-- Ports `3000`, `3100`, `9000`, and `9001` available on the host.
-- A Linux or macOS host (or WSL2 on Windows).
-- A **MongoDB Atlas** cluster (a free tier works). Create one at [mongodb.com/atlas](https://www.mongodb.com/atlas).
-- A **Resend** API key for transactional email. Get one at [resend.com](https://resend.com). A [global SMTP mailer](#global-mailer) works instead.
+### Prerequisites
 
-Everything else — Bun, Redis, MinIO, Chromium — ships inside the image.
+- **Docker** ≥ 24: the installer offers to install it (via [get.docker.com](https://get.docker.com) on Linux, Homebrew on macOS). On Windows, install [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (WSL 2 backend) first.
+- Ports `3000`, `3100`, `9000` and `9001` free on the host. MinIO `9000` must stay reachable by the browser, which loads assets straight from `S3_PUBLIC_URL`.
+- A mailer: a [Resend](https://resend.com) API key or an SMTP relay.
 
-## Quick start
+### 1. Install
 
-### 1. Run the installer
+Writes `./intlayer.env` with `BETTER_AUTH_SECRET` and `S3_SECRET_ACCESS_KEY` generated, asks a few questions to fill in the rest, and pulls `intlayer/cms-all:latest`.
+
+<Tabs group="os">
+<Tab label="macOS / Linux" value="unix">
 
 ```sh
-curl -fsSL https://intlayer.org/install.sh | sh
+curl -fsSL https://intlayer.org/install.sh | sh -s -- --mode docker
 ```
 
-It verifies Docker is installed and running, writes `./intlayer.env` with `BETTER_AUTH_SECRET` and `S3_SECRET_ACCESS_KEY` already generated, and pulls the image. It does not start the container — the backend cannot boot without your database credentials.
+</Tab>
+<Tab label="Windows" value="windows">
+
+In PowerShell:
 
-Re-running the installer is safe: an existing `intlayer.env` is never overwritten, so it doubles as the upgrade path.
+```powershell
+$env:INTLAYER_MODE = "docker"; irm https://intlayer.org/install.ps1 | iex
+```
 
-### 2. Fill in your credentials
+</Tab>
+<Tab label="Intlayer CLI" value="cli">
+
+```bash
+npx intlayer init infra --mode docker
+```
 
-Open `intlayer.env` and complete the values marked `TODO`:
+</Tab>
+</Tabs>
+
+### 2. Answer the setup questions
+
+The installer asks for (press Enter to accept a suggestion, every answer can be changed in the file later):
+
+- **The domain** Intlayer is served on. Leave it empty to stay on `localhost`. With a domain such as `example.org`, it suggests `https://cms.example.org` for the dashboard, `https://back.example.org` for the API and `https://s3.example.org/intlayer` for the object storage, and writes `DOMAIN`, `APP_URL`, `BACKEND_URL` and `S3_PUBLIC_URL`. See [Custom domain](#custom-domain) for what follows.
+- **The mailer**: Resend (API key) or an SMTP relay (host, port, credentials), plus the sender address. This can be skipped and done by hand later.
+- An optional **OpenAI API key** for the AI features.
+
+Without a terminal (for instance when the script is run from CI), the questions are skipped and only the secrets are generated. Open `intlayer.env` and fill in Resend **or** SMTP by hand (details in [Global mailer](#global-mailer)):
 
 ```sh fileName="intlayer.env"
-DB_ID=<atlas-user>
-DB_MDP=<atlas-password>
-DB_CLUSTER=<cluster>.xxxxx.mongodb.net
+# Option A: Resend
 RESEND_API_KEY=<your-resend-key>
-```
 
-The file also carries commented-out blocks for the optional features — [SMTP mailer](#global-mailer), `OPENAI_API_KEY`, and the OAuth providers. Uncomment what you need.
+# Option B: SMTP (takes over from Resend as soon as MAIL_SMTP_HOST is set)
+MAIL_SMTP_HOST=smtp.example.com
+MAIL_SMTP_PORT=587
+MAIL_SMTP_USER=<user>
+MAIL_SMTP_PASSWORD=<password>
+MAIL_FROM=Intlayer <no-reply@example.com>
+```
 
-> The file is read by `docker run --env-file`, which does not strip quotes and treats everything after `=` as the value. Write bare values, and keep comments on their own lines.
+### 3. Start
 
-### 3. Start the container
+This is the command the installer prints (with a custom domain, it is preceded by the `docker build` that produces `intlayer/cms-all:custom`, see [Custom domain](#custom-domain)):
 
-This is the command the installer prints when it finishes:
+<Tabs group="os">
+<Tab label="macOS / Linux" value="unix">
 
 ```sh
 docker run -d --name intlayer \
   --restart unless-stopped \
-  -p 3000:3000 \
-  -p 3100:3100 \
-  -p 9000:9000 \
-  -p 9001:9001 \
+  -p 3000:3000 -p 3100:3100 -p 9000:9000 -p 9001:9001 \
   -v intlayer-data:/data \
   --env-file ./intlayer.env \
-  ghcr.io/aymericzip/intlayer-selfhost:latest
+  intlayer/cms-all:latest
+```
+
+</Tab>
+<Tab label="Windows" value="windows">
+
+```powershell
+docker run -d --name intlayer `
+  --restart unless-stopped `
+  -p 3000:3000 -p 3100:3100 -p 9000:9000 -p 9001:9001 `
+  -v intlayer-data:/data `
+  --env-file ./intlayer.env `
+  intlayer/cms-all:latest
 ```
 
-Then open **http://localhost:3000**. First boot initialises the datastores, so give it a minute.
+</Tab>
+<Tab label="Intlayer CLI" value="cli">
 
-> The dashboard is served on `localhost`. See [Limitations](#limitations) — custom domains are not supported by the published image.
+The CLI runs the installer, which prints the `docker run …` command shown in the other tabs. Copy it into your terminal once the mailer is configured.
+
+</Tab>
+</Tabs>
+
+Open **http://localhost:3000** (or your dashboard URL) and follow [First-run setup](#first-run-setup). The first boot initialises the replica set and the bucket, so give it a minute.
+
+### Backup and upgrade
+
+All state lives in the `intlayer-data` volume (`/data/mongo`, `/data/redis`, `/data/minio`).
+
+```sh
+# Backup (stop the container first so MongoDB's files are consistent)
+docker stop intlayer
+docker run --rm -v intlayer-data:/data -v "$(pwd)":/backup busybox tar czf /backup/intlayer-data.tar.gz /data
+docker start intlayer
+
+# Restore
+docker run --rm -v intlayer-data:/data -v "$(pwd)":/backup busybox tar xzf /backup/intlayer-data.tar.gz -C /
+```
+
+To upgrade, re-run the installer (it pulls the latest image and keeps `intlayer.env`), then `docker rm -f intlayer` and run the start command again. To use a managed MongoDB instead of the bundled one, set `MONGODB_URI` in `intlayer.env`.
+
+</Tab>
+<Tab label="Docker Compose" value="compose">
+
+One container per service on a private Compose network. The dashboard and the API use the published `intlayer/cms-frontend` and `intlayer/cms-backend` images; the datastores use the official `mongo`, `redis` and `minio` images.
+
+```
+                ┌───────────────────┐
+ browser ──────▶ │  app        :3000 │ ── SSR ──▶ http://backend:3100
+ (localhost)    └───────────────────┘
+                ┌───────────────────┐
+ browser ──────▶ │  backend    :3100 │
+ (localhost)    └─────────┬─────────┘
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+     mongo:27017     redis:6379      minio:9000 ◀── browser (assets)
+     (1-node RS)                     minio:9001
+```
+
+| Service      | Image                   | Role                                                                      |
+| ------------ | ----------------------- | ------------------------------------------------------------------------- |
+| `app`        | `intlayer/cms-frontend` | Dashboard on `:3000`; waits for the backend to be healthy                 |
+| `backend`    | `intlayer/cms-backend`  | API on `:3100` with Chromium; waits for Mongo, Redis and the MinIO bucket |
+| `mongo`      | `mongo:8`               | Single-node replica set `rs0`, initiated by its own healthcheck           |
+| `redis`      | `redis:8-alpine`        | Queues and caching, append-only persistence                               |
+| `minio`      | `quay.io/minio/minio`   | S3 storage on `:9000`, console on `:9001`                                 |
+| `minio-init` | `quay.io/minio/mc`      | One-shot: creates the bucket and its anonymous-download policy            |
+
+Data is kept in the `intlayer_mongo-data`, `intlayer_redis-data` and `intlayer_minio-data` volumes. The service wiring (`MONGODB_URI`, `REDIS_URL`, `S3_ENDPOINT`, the internal backend URL used by server-side rendering) is fixed in the compose file and takes precedence over `.env`, which only carries secrets and optional integrations.
+
+### Prerequisites
+
+- **Docker** ≥ 24 with the Compose plugin: the installer offers to install it on Linux and macOS. On Windows, install [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (WSL 2 backend) first.
+- Ports `3000`, `3100`, `9000` and `9001` free on the host.
+- A mailer: a [Resend](https://resend.com) API key or an SMTP relay.
+
+### 1. Install
+
+Writes `docker-compose.yml` and a `.env` with the secrets generated into `./intlayer/`, asks the same setup questions as the all-in-one mode (domain, mailer, OpenAI key), and pulls the images.
+
+<Tabs group="os">
+<Tab label="macOS / Linux" value="unix">
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh -s -- --mode compose
+```
+
+Or by hand:
+
+```sh
+mkdir intlayer && cd intlayer
+curl -fsSLO https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/docker-compose.yml
+curl -fsSL  https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/.env.template -o .env
+# fill in BETTER_AUTH_SECRET and S3_SECRET_ACCESS_KEY (openssl rand -hex 32)
+```
+
+</Tab>
+<Tab label="Windows" value="windows">
+
+In PowerShell:
+
+```powershell
+$env:INTLAYER_MODE = "compose"; irm https://intlayer.org/install.ps1 | iex
+```
+
+Or by hand:
+
+```powershell
+mkdir intlayer; cd intlayer
+irm https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/docker-compose.yml -OutFile docker-compose.yml
+irm https://raw.githubusercontent.com/aymericzip/intlayer/main/docker/selfhost/.env.template -OutFile .env
+# fill in BETTER_AUTH_SECRET and S3_SECRET_ACCESS_KEY
+```
+
+</Tab>
+<Tab label="Intlayer CLI" value="cli">
+
+```bash
+npx intlayer init infra --mode compose
+```
+
+</Tab>
+</Tabs>
+
+### 2. Configure a mailer
+
+If you skipped the mailer question, fill in Resend **or** SMTP in `intlayer/.env`, exactly as for the all-in-one container (see [Global mailer](#global-mailer)).
+
+### 3. Start
+
+```sh
+cd intlayer && docker compose up -d
+```
+
+With a custom domain, the installer also downloads `docker-compose.build.yml` and the start command becomes `docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build` (see [Custom domain](#custom-domain)).
+
+Open **http://localhost:3000** (or your dashboard URL) and follow [First-run setup](#first-run-setup).
+
+### Managed datastores
+
+Delete the service you are replacing from the compose file (and its `depends_on` entry on `backend`), then override the matching variable:
+
+```yaml fileName="docker-compose.yml"
+services:
+  backend:
+    environment:
+      MONGODB_URI: mongodb+srv://user:password@cluster0.xxxxx.mongodb.net/intlayer
+      REDIS_URL: rediss://default:password@redis.example.com:6380
+      S3_ENDPOINT: https://s3.eu-west-1.amazonaws.com
+      S3_PUBLIC_URL: https://intlayer-assets.s3.eu-west-1.amazonaws.com
+```
+
+`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` / `S3_BUCKET_NAME` keep their meaning against any S3-compatible provider.
+
+### Scaling
+
+`app` and `backend` are stateless. Behind a load balancer, `docker compose up -d --scale backend=3` works once the fixed host port mappings are removed and the proxy addresses the services by name. Background jobs are coordinated through Redis (BullMQ), so several backend replicas share the queue safely.
+
+### Building from source
+
+An override switches the two Intlayer services from `image:` to `build:`. From a checkout of the repository:
+
+```sh
+cd docker/selfhost
+docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+```
+
+Without a checkout, point the build context at the repository itself by setting `INTLAYER_BUILD_CONTEXT=https://github.com/aymericzip/intlayer.git#main` in `.env`. The dashboard's `VITE_*` build args follow `DOMAIN`, `APP_URL` and `BACKEND_URL` from the same file, which is how a [custom domain](#custom-domain) is applied.
+
+### Backup and upgrade
+
+```sh
+# Backup one volume (repeat for intlayer_redis-data and intlayer_minio-data)
+docker compose stop
+docker run --rm -v intlayer_mongo-data:/data -v "$(pwd)":/backup busybox tar czf /backup/mongo-data.tar.gz /data
+docker compose start
+
+# Upgrade, volumes are kept
+docker compose pull && docker compose up -d
+```
+
+</Tab>
+</Tabs>
 
 ### Installer settings
 
-The installer reads a few environment variables. Because it is piped into `sh`, pass them to the shell rather than to `curl`:
+Without `--mode` (or `INTLAYER_MODE`), the installer shows a menu: `desktop`, `docker` (all-in-one) or `compose`. It also reads a few environment variables. Because it is piped into the shell, pass them to the shell rather than to `curl`:
 
 ```sh
-curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh
+curl -fsSL https://intlayer.org/install.sh | INTLAYER_COMPOSE_DIR=./cms sh -s -- --mode compose
 ```
 
-| Variable                  | Default                                       | Description                     |
-| ------------------------- | --------------------------------------------- | ------------------------------- |
-| `INTLAYER_IMAGE`          | `ghcr.io/aymericzip/intlayer-selfhost:latest` | Image to pull                   |
-| `INTLAYER_ENV_FILE`       | `./intlayer.env`                              | Where to write the env file     |
-| `INTLAYER_CONTAINER_NAME` | `intlayer`                                    | Container name                  |
-| `INTLAYER_DATA_VOLUME`    | `intlayer-data`                               | Named volume mounted at `/data` |
-| `INTLAYER_APP_PORT`       | `3000`                                        | Host port for the dashboard     |
-| `INTLAYER_API_PORT`       | `3100`                                        | Host port for the API           |
-| `INTLAYER_S3_PORT`        | `9000`                                        | Host port for the MinIO S3 API  |
-| `INTLAYER_CONSOLE_PORT`   | `9001`                                        | Host port for the MinIO console |
+```powershell
+$env:INTLAYER_MODE = "compose"; $env:INTLAYER_COMPOSE_DIR = ".\cms"; irm https://intlayer.org/install.ps1 | iex
+```
 
-> The four port variables only change the **host** side of the mapping printed in the `docker run` command. The published image has `http://localhost:3000`, `http://localhost:3100` and `http://localhost:9000` compiled into the dashboard bundle at build time, so remapping them leaves the browser pointing at the old ports. Keep the defaults unless you are building your own image — see [Limitations](#limitations).
+| Variable                  | Default                   | Applies to | Description                                                |
+| ------------------------- | ------------------------- | ---------- | ---------------------------------------------------------- |
+| `INTLAYER_MODE`           | _(asked)_                 | all        | `desktop`, `docker` or `compose`, same as `--mode`         |
+| `INTLAYER_DOWNLOAD_DIR`   | `~/Downloads`             | desktop    | Where the app installer is saved                           |
+| `INTLAYER_IMAGE`          | `intlayer/cms-all:latest` | docker     | All-in-one image to pull                                   |
+| `INTLAYER_ENV_FILE`       | `./intlayer.env`          | docker     | Where to write the environment file                        |
+| `INTLAYER_CONTAINER_NAME` | `intlayer`                | docker     | Container name                                             |
+| `INTLAYER_DATA_VOLUME`    | `intlayer-data`           | docker     | Named volume mounted at `/data`                            |
+| `INTLAYER_APP_PORT`       | `3000`                    | docker     | Host port for the dashboard                                |
+| `INTLAYER_API_PORT`       | `3100`                    | docker     | Host port for the API                                      |
+| `INTLAYER_S3_PORT`        | `9000`                    | docker     | Host port for the MinIO S3 API                             |
+| `INTLAYER_CONSOLE_PORT`   | `9001`                    | docker     | Host port for the MinIO console                            |
+| `INTLAYER_COMPOSE_DIR`    | `./intlayer`              | compose    | Where `docker-compose.yml` and `.env` are written          |
+| `INTLAYER_SELFHOST_REF`   | `main`                    | both       | Git ref the compose file and env template are fetched from |
+| `INTLAYER_BUILD_CONTEXT`  | `…/intlayer.git#main`     | both       | Build context used when a custom domain requires a rebuild |
+| `INTLAYER_CUSTOM_IMAGE`   | `intlayer/cms-all:custom` | docker     | Tag of the all-in-one image built for a custom domain      |
+
+> The port variables only change the **host** side of the mapping. The published images have `http://localhost:3000`, `http://localhost:3100` and `http://localhost:9000` compiled into the dashboard bundle, so remapping them leaves the browser pointing at the old ports. Keep the defaults unless you build your own images, see [Limitations](#limitations).
 
 ## First-run setup
 
 On a fresh instance (empty database), opening the dashboard redirects you to the **`/init`** page:
 
 1. Create the first account. Because the users collection is empty, this account is automatically promoted to **super admin**.
-2. A verification email is sent (via Resend). Email verification is **mandatory** — this is why `RESEND_API_KEY` must be set before you start.
+2. A verification email is sent through Resend or your SMTP relay. Email verification is **mandatory**, this is why a mailer must be configured before you start.
 3. Click the link in the email, then sign in.
 
 Once an admin exists, `/init` redirects to the standard sign-in page.
 
-## Services
+## Environment variables
 
-| Service     | Location           | Host port(s)                  | Purpose                                                       |
-| ----------- | ------------------ | ----------------------------- | ------------------------------------------------------------- |
-| **app**     | bundled            | `3000`                        | TanStack Start dashboard (CMS UI)                             |
-| **backend** | bundled            | `3100`                        | Fastify REST API (`/health` endpoint)                         |
-| **redis**   | bundled            | internal                      | Job queues (BullMQ) and caching (ioredis)                     |
-| **minio**   | bundled            | `9000` (S3), `9001` (console) | S3-compatible object storage for avatars and screenshots      |
-| **mongo**   | **external** (you) | —                             | MongoDB Atlas, provided via `DB_ID` / `DB_MDP` / `DB_CLUSTER` |
+Both Docker modes read the same file (`intlayer.env` for the container, `.env` for Compose), generated from [`docker/selfhost/.env.template`](https://github.com/aymericzip/intlayer/blob/main/docker/selfhost/.env.template).
 
-> MinIO port `9000` must be reachable by the browser because uploaded assets (avatars, screenshots) are loaded directly from `S3_PUBLIC_URL=http://localhost:9000/intlayer`.
+### Required
 
-## Environment variables
+| Variable               | Example       | Description                                                                                                                                   |
+| ---------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`   | _(generated)_ | 32-byte secret for session signing                                                                                                            |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_ | Secret for the bundled MinIO                                                                                                                  |
+| `RESEND_API_KEY`       | _(your key)_  | Transactional email via Resend. Required for first-run setup unless an SMTP relay is configured instead (see [Global mailer](#global-mailer)) |
 
-### Required
+### Fixed by the deployment
+
+These are set by the image (all-in-one) or by the compose file, and only need overriding for a non-standard topology. `DOMAIN`, `APP_URL`, `BACKEND_URL` and `S3_PUBLIC_URL` are the exception: set in the env file, they take precedence in both modes (see [Custom domain](#custom-domain)).
+
+| Variable           | All-in-one                                          | Docker Compose                   | Description                                                                   |
+| ------------------ | --------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------- |
+| `PORT`             | `3100`                                              | `3100`                           | Backend listening port                                                        |
+| `APP_URL`          | `http://localhost:3000`                             | `http://localhost:3000`          | Public URL of the dashboard                                                   |
+| `BACKEND_URL`      | `http://localhost:3100`                             | `http://localhost:3100`          | Public URL of the backend API                                                 |
+| `DOMAIN`           | `localhost`                                         | `localhost`                      | Cookie domain                                                                 |
+| `SELF_HOSTED`      | `true`                                              | `true`                           | Disables the cloud-only API endpoints (billing, subscriptions, marketplace)   |
+| `MONGODB_URI`      | `mongodb://127.0.0.1:27017/intlayer?replicaSet=rs0` | `mongodb://mongo:27017/…`        | MongoDB connection string, any `mongodb://` or `mongodb+srv://` cluster works |
+| `REDIS_URL`        | `redis://127.0.0.1:6379`                            | `redis://redis:6379`             | Redis                                                                         |
+| `S3_ENDPOINT`      | `http://127.0.0.1:9000`                             | `http://minio:9000`              | MinIO (server-to-server)                                                      |
+| `S3_PUBLIC_URL`    | `http://localhost:9000/intlayer`                    | `http://localhost:9000/intlayer` | Public URL for browser asset loading                                          |
+| `S3_BUCKET_NAME`   | `intlayer`                                          | `intlayer`                       | Bucket name                                                                   |
+| `S3_ACCESS_KEY_ID` | `intlayer`                                          | `intlayer`                       | MinIO access key                                                              |
+
+The Compose `app` service additionally receives `INTLAYER_BACKEND_INTERNAL_URL=http://backend:3100`: the browser reaches the API on `localhost:3100`, but server-side rendering runs inside the Compose network and must use the service name.
+
+### Custom domain
+
+The backend reads its public URLs at runtime, but the dashboard has them **compiled in**: the published `intlayer/cms-frontend` and `intlayer/cms-all` images only work on `http://localhost:3000`. Serving Intlayer on your own domain therefore takes two things, both prepared by the installer when you answer the domain question:
 
-| Variable               | Example                      | Description                                                                                                                                  |
-| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DB_ID`                | `intlayer`                   | MongoDB Atlas user                                                                                                                           |
-| `DB_MDP`               | _(your password)_            | MongoDB Atlas password                                                                                                                       |
-| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas cluster host (used in the `mongodb+srv://` URI)                                                                                |
-| `BETTER_AUTH_SECRET`   | _(generated)_                | 32-byte secret for session signing                                                                                                           |
-| `S3_SECRET_ACCESS_KEY` | _(generated)_                | Secret for the bundled MinIO                                                                                                                 |
-| `RESEND_API_KEY`       | _(your key)_                 | Transactional email via Resend. Required for first-run setup unless you configure a global SMTP mailer (see [Global mailer](#global-mailer)) |
-| `SELF_HOSTED`          | `true`                       | Disables the cloud-only API endpoints: Stripe billing, subscriptions, affiliate and promo-code programs, and the reviewer marketplace        |
-
-### Baked-in defaults (override only if needed)
-
-| Variable           | Default                          | Description                          |
-| ------------------ | -------------------------------- | ------------------------------------ |
-| `PORT`             | `3100`                           | Backend listening port               |
-| `APP_URL`          | `http://localhost:3000`          | Public URL of the dashboard          |
-| `BACKEND_URL`      | `http://localhost:3100`          | Public URL of the backend API        |
-| `DOMAIN`           | `localhost`                      | Cookie domain                        |
-| `REDIS_URL`        | `redis://127.0.0.1:6379`         | Bundled Redis                        |
-| `S3_ENDPOINT`      | `http://127.0.0.1:9000`          | Bundled MinIO (server-to-server)     |
-| `S3_PUBLIC_URL`    | `http://localhost:9000/intlayer` | Public URL for browser asset loading |
-| `S3_BUCKET_NAME`   | `intlayer`                       | Bucket name                          |
-| `S3_ACCESS_KEY_ID` | `intlayer`                       | MinIO access key                     |
+1. **Four variables in the env file**, read by the backend (cookies, email links, OAuth callbacks, asset URLs) and used as build args by `docker-compose.build.yml`:
+
+   ```sh fileName="intlayer.env"
+   DOMAIN=example.org                          # cookie domain, parent of the hosts below
+   APP_URL=https://cms.example.org
+   BACKEND_URL=https://back.example.org
+   S3_PUBLIC_URL=https://s3.example.org/intlayer
+   ```
+
+2. **A dashboard image built with those URLs.** Docker builds it straight from the repository, no checkout needed:
+
+   ```sh
+   # Docker Compose: the override reads the build args from .env
+   docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+
+   # All-in-one
+   docker build -f docker/selfhost/Dockerfile \
+     --build-arg VITE_DOMAIN=example.org \
+     --build-arg VITE_SITE_URL=https://cms.example.org \
+     --build-arg VITE_IDE_URL=https://cms.example.org \
+     --build-arg VITE_BACKEND_URL=https://back.example.org \
+     -t intlayer/cms-all:custom \
+     https://github.com/aymericzip/intlayer.git#main
+   ```
+
+Then put a reverse proxy with TLS in front of the container: `cms.example.org` → port `3000`, `back.example.org` → `3100`, `s3.example.org` → `9000`. The three hosts must share the `DOMAIN` suffix, since the session cookie is scoped to it.
 
 ### Optional (features degrade gracefully when absent)
 
-| Variable                                                 | Feature                                   |
-| -------------------------------------------------------- | ----------------------------------------- |
-| `OPENAI_API_KEY`                                         | AI-assisted translation and content audit |
-| `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_*` | Billing and subscription management       |
-| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`               | GitHub OAuth login                        |
-| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`               | Google OAuth login                        |
-| `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`               | GitLab OAuth login                        |
-| `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`         | Microsoft OAuth login                     |
+| Variable                                         | Feature                                   |
+| ------------------------------------------------ | ----------------------------------------- |
+| `OPENAI_API_KEY`                                 | AI-assisted translation and content audit |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`       | GitHub OAuth login                        |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`       | Google OAuth login                        |
+| `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`       | GitLab OAuth login                        |
+| `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET` | Microsoft OAuth login                     |
 
 ### Global mailer
 
-By default, all transactional emails are sent through Resend using `RESEND_API_KEY`. Self-hosted deployments can instead route **every** email — including non-organization emails such as password resets and magic links — through a global mailer configured with environment variables.
+Every transactional email, including non-organization emails such as password resets and magic links, goes through one of two global transports:
 
-Set `MAIL_PROVIDER` to activate it. When unset, the default Resend mailer is used.
+- **Resend**, using `RESEND_API_KEY`.
+- **SMTP**, using the `MAIL_SMTP_*` variables. As soon as `MAIL_SMTP_HOST` is set, SMTP is used and `RESEND_API_KEY` is ignored.
 
-| Variable             | Example                        | Description                                                       |
-| -------------------- | ------------------------------ | ----------------------------------------------------------------- |
-| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` or `resend`. Leave unset to use defaults |
-| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header. Accepts a bare address or `Name <email>` format    |
-| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (required when `MAIL_PROVIDER=smtp`)                    |
-| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (defaults to `587`)                                     |
-| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Set `true` for port `465`                           |
-| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP username (optional; omit for unauthenticated relays)         |
-| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP password                                                     |
+`MAIL_PROVIDER` is only needed to force one transport when both are configured (for instance `MAIL_PROVIDER=resend` to keep Resend while an SMTP host is present).
+
+| Variable             | Example                        | Description                                                                  |
+| -------------------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header for either transport. Accepts a bare address or `Name <email>` |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host. Setting it selects the SMTP transport                             |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (defaults to `587`)                                                |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Set `true` for port `465`                                      |
+| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP username (optional; omit for unauthenticated relays)                    |
+| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP password                                                                |
+| `MAIL_PROVIDER`      | `resend`                       | Optional override: `smtp` or `resend`. Leave unset to auto-select            |
 
 > Precedence: an organization's own mailer (configured from the **Organization** dashboard) takes priority over the global mailer, which in turn takes priority over the default Resend key.
 
@@ -271,73 +568,18 @@ const cms = createIntlayerCMS({
 const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
 ```
 
-## Upgrading
-
-Re-run the installer to pull the latest image, then recreate the container. Your `intlayer.env` is left untouched, and your data is preserved in the named volume (MinIO/Redis) and in your Atlas cluster (MongoDB):
-
-```sh
-curl -fsSL https://intlayer.org/install.sh | sh
-docker rm -f intlayer
-# re-run the `docker run …` command from step 3 of Quick start
-```
-
-## Backup and restore
-
-MongoDB data lives in your Atlas cluster — back it up with Atlas' own tools. The bundled local datastores live under the `intlayer-data` volume.
-
-### Backup
-
-```sh
-docker run --rm \
-  -v intlayer-data:/data \
-  -v "$(pwd)":/backup \
-  busybox tar czf /backup/intlayer-data.tar.gz /data
-```
-
-### Restore
-
-```sh
-docker run --rm \
-  -v intlayer-data:/data \
-  -v "$(pwd)":/backup \
-  busybox tar xzf /backup/intlayer-data.tar.gz -C /
-```
-
 ## Limitations
 
-- **MongoDB must be external (Atlas).** The backend connects only over `mongodb+srv://` (built from `DB_ID` / `DB_MDP` / `DB_CLUSTER`), so a plain `mongodb://host:27017` — including the container's own bundled `mongod` — cannot be used. Provide a MongoDB Atlas cluster.
-- **No custom domain, and no port remapping.** All browser-facing `VITE_*` URLs are inlined into the app at build time, and the published image ships with `localhost` values. The dashboard must be accessed at `http://localhost:3000`, the API at `:3100` and MinIO at `:9000`; serving it on a public domain — or on different ports — would require rebuilding the image with the target URLs baked in (`--build-arg VITE_BACKEND_URL=…`) and is not supported out of the box.
-- **Email requires a working mailer.** First-run setup enforces email verification, so either `RESEND_API_KEY` or a [global SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) must be configured. After the first admin signs in, each organization can also configure its own SMTP or Resend mailer from the dashboard.
-
-## Troubleshooting
-
-### Dashboard loads but the API resets the connection (`ERR_CONNECTION_RESET` on `:3100`)
-
-The backend crashed on startup and is not listening. The most common cause is a missing or invalid MongoDB connection — usually the `TODO` values in `intlayer.env` were never filled in:
-
-```sh
-grep -E '^DB_(ID|MDP|CLUSTER)=' intlayer.env
-docker logs intlayer
-```
-
-Look for `MongoDB connection error` near the top of the log. After correcting `intlayer.env`, recreate the container (`docker rm -f intlayer`, then the `docker run …` command again) — `--env-file` is read at creation time, so editing the file does not affect a running container.
-
-### First account can't be verified
-
-Email verification is mandatory. Make sure a mailer is configured — either `RESEND_API_KEY`, or a [global SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) — then re-check your inbox (and spam). Without a working mailer, the verification link is never delivered. Delivery failures are logged by the backend (`docker logs intlayer`) with the underlying error message.
-
-### MinIO bucket missing
-
-The `init-minio` one-shot creates the bucket on first boot. If assets fail to load, restart the container so it runs again:
-
-```sh
-docker restart intlayer
-```
+- **A custom domain means a rebuild.** All browser-facing `VITE_*` URLs are inlined into the dashboard at build time, and the published images (and the desktop app) ship with `localhost` / Intlayer Cloud values. Out of the box the dashboard must be accessed at `http://localhost:3000`, the API at `:3100` and MinIO at `:9000`; remapping the host ports has the same effect. The installer wires everything for a rebuild from the repository when you give it a domain (see [Custom domain](#custom-domain)), but the build itself takes several minutes. Pointing the desktop app at a self-hosted backend is not supported.
+- **Email requires a working mailer.** First-run setup enforces email verification, so either `RESEND_API_KEY` or an [SMTP relay](#global-mailer) (`MAIL_SMTP_*`) must be configured. After the first admin signs in, each organization can also configure its own SMTP or Resend mailer from the dashboard.
+- **The desktop app needs Node.js** on the machine to start its embedded server.
+- **No documentation assistant.** The AI doc assistant of intlayer.org (`/api/ai/ask`, `/api/search/doc`) relies on ~130 MB of pre-computed documentation embeddings that the self-host images do not ship; those two routes are not registered in self-hosted mode. The dashboard's own AI features (translation, audit, autocomplete, chat) are unaffected and only need `OPENAI_API_KEY`.
 
 ## Useful links
 
 - [Intlayer CMS documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
 - [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
-- [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)
-- [Container image on GHCR](https://github.com/aymericzip/intlayer/pkgs/container/intlayer-selfhost) — `ghcr.io/aymericzip/intlayer-selfhost`
-- [Container image on Docker Hub](https://hub.docker.com/r/aymericzip/intlayer-selfhost) — mirror of the same build
+- [CMS SDK: `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)
+- [Desktop app releases](https://github.com/aymericzip/intlayer/releases/latest)
+- Docker Hub: [`intlayer/cms-all`](https://hub.docker.com/r/intlayer/cms-all), [`intlayer/cms-frontend`](https://hub.docker.com/r/intlayer/cms-frontend), [`intlayer/cms-backend`](https://hub.docker.com/r/intlayer/cms-backend), mirrored on GHCR under `ghcr.io/aymericzip/intlayer/`
+- [`docker/selfhost/`](https://github.com/aymericzip/intlayer/tree/main/docker/selfhost): Dockerfile, `docker-compose.yml` and `.env.template`