@intlayer/docs 9.5.6 → 9.5.7

package/docs/en-GB/self_hosting.md

@@ -1,12 +1,13 @@
 ---
 createdAt: 2026-06-30
-updatedAt: 2026-06-30
+updatedAt: 2026-09-21
 title: Self-Hosting Intlayer
-description: Run a complete Intlayer instance on your own infrastructure with a single command. 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
@@ -19,210 +20,451 @@ author: aymericzip
 
 # Self-Hosting Intlayer
 
-Intlayer can run entirely on your own infrastructure. No Intlayer Cloud account required. A single command boots a production-ready stack:
+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 downloads a `docker-compose.yml` and a `.env`, auto-generates the required secrets, and starts all containers with `docker compose up -d`.
+</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">
 
-## Architecture
+```bash
+npx intlayer init infra --mode desktop
+```
+
+</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.
 
 ```
                 ┌─────────────────────────────┐
  browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
-                └─────────────────────────────┘   │ VITE_BACKEND_URL
+ (localhost)    └─────────────────────────────┘   │ VITE_BACKEND_URL (baked at build)
                 ┌─────────────────────────────┐   │
                 │  backend (Fastify/Bun)  :3100│ ◀─┘
                 └──────────────┬──────────────┘
-          ┌──────────┬─────────┼──────────┬───────────┐
-          ▼          ▼         ▼          ▼           ▼
-     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium
-     (1-node RS)             (S3 API)     (SMTP)        (in-image)
-                             minio:9001   mailpit:8025
-                             (console)    (web UI)
+          ┌──────────┬─────────┼──────────────┐
+          ▼          ▼         ▼               ▼
+      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 backend image. No separate container is needed.
+| 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 |
+
+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.
 
-## Prerequisites
+### Prerequisites
 
-- **Docker** ≥ 24 and **Docker Compose** ≥ v2. If either is missing, the installer prints the install link and exits.
-- Ports `3000`, `3100`, `8025`, `9000`, and `9001` available on the host.
-- A Linux or macOS host (or WSL2 on Windows).
+- **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.
 
-Everything else — Bun, Redis, MinIO, Chromium — ships inside the image.
+### 1. Install
 
-## Quick start
+Writes `./intlayer.env` with `BETTER_AUTH_SECRET` and `S3_SECRET_ACCESS_KEY` generated, and pulls `intlayer/cms-all:latest`.
 
-### 1. Run the installer
+<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">
 
-Re-running the installer is safe: an existing `intlayer.env` is never overwritten, so it doubles as the upgrade path.
+In PowerShell:
 
-### 2. Fill in your credentials
+```powershell
+$env:INTLAYER_MODE = "docker"; irm https://intlayer.org/install.ps1 | iex
+```
 
-Open `intlayer.env` and complete the values marked `TODO`:
+</Tab>
+<Tab label="Intlayer CLI" value="cli">
+
+```bash
+npx intlayer init infra --mode docker
+```
+
+</Tab>
+</Tabs>
+
+### 2. Configure a mailer
+
+Open `intlayer.env` and fill in Resend **or** SMTP (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:
 
-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
 ```
 
-Then open **http://localhost:3000**. First boot initialises the datastores, so give it a minute.
+</Tab>
+<Tab label="Windows" value="windows">
 
-> The dashboard is served on `localhost`. See [Limitations](#limitations) — custom domains are not supported by the published image.
+```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
+```
 
-### Installer settings
+</Tab>
+<Tab label="Intlayer CLI" value="cli">
+
+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** 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/`, 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:
 
-The installer reads a few environment variables. Because it is piped into `sh`, pass them to the shell rather than to `curl`:
+```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
+
+Fill in Resend **or** SMTP in `intlayer/.env`, exactly as for the all-in-one container (see [Global mailer](#global-mailer)).
+
+### 3. Start
 
 ```sh
-curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh
+cd intlayer && docker compose up -d
+```
+
+Open **http://localhost:3000** 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
 ```
 
-| 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 |
+`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` / `S3_BUCKET_NAME` keep their meaning against any S3-compatible provider.
 
-> 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).
+### Scaling
 
-## Quick start
+`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.
 
-What the installer does:
+### Building from source
 
-1. Checks that `docker` and `docker compose` are present.
-2. Downloads `docker-compose.yml` and `.env.example` into `./intlayer/`.
-3. If no `.env` exists, copies the example and generates random secrets for `BETTER_AUTH_SECRET`, `S3_ACCESS_KEY_ID`, and `S3_SECRET_ACCESS_KEY` via `openssl rand`.
-4. Runs `docker compose pull` + `docker compose up -d`.
-5. Prints the URLs: dashboard `:3000`, API `:3100`, email UI `:8025`, MinIO console `:9001`.
+From a checkout of the repository, an override switches the two Intlayer services from `image:` to `build:`:
 
-After the stack is up, open **http://localhost:3000** and create your first account.
+```sh
+cd docker/selfhost
+docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
+```
+
+This is also how you produce images for a custom domain: pass the `VITE_*` values as build args (see [Limitations](#limitations)).
 
-## Services
+### Backup and upgrade
 
-| Service     | Image                                | Host port(s)                   | Purpose                                                  |
-| ----------- | ------------------------------------ | ------------------------------ | -------------------------------------------------------- |
-| **app**     | built from `apps/app/Dockerfile`     | `3000`                         | TanStack Start dashboard (CMS UI)                        |
-| **backend** | built from `apps/backend/Dockerfile` | `3100`                         | Fastify REST API (`/health` endpoint)                    |
-| **mongo**   | `mongo:7`                            | internal                       | Single-node replica set (`rs0`)                          |
-| **redis**   | `redis:7-alpine`                     | internal                       | Job queues (BullMQ) and caching (ioredis)                |
-| **minio**   | `minio/minio`                        | `9000` (S3), `9001` (console)  | S3-compatible object storage for avatars and screenshots |
-| **mailpit** | `axllent/mailpit`                    | `1025` (SMTP), `8025` (web UI) | Local transactional email sink                           |
+```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
 
-> 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`.
+# Upgrade, volumes are kept
+docker compose pull && docker compose up -d
+```
+
+</Tab>
+</Tabs>
+
+### Installer settings
+
+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_COMPOSE_DIR=./cms sh -s -- --mode compose
+```
+
+```powershell
+$env:INTLAYER_MODE = "compose"; $env:INTLAYER_COMPOSE_DIR = ".\cms"; irm https://intlayer.org/install.ps1 | iex
+```
+
+| 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 |
+
+> 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 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.
 
 ## Environment variables
 
+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).
+
 ### Required
 
-| 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)) |
-
-### Required (auto-generated or prompted)
-
-| Variable               | Example                                         | Description                                        |
-| ---------------------- | ----------------------------------------------- | -------------------------------------------------- |
-| `NODE_ENV`             | `production`                                    | Runtime environment                                |
-| `PORT`                 | `3100`                                          | Backend listening port                             |
-| `BACKEND_URL`          | `http://localhost:3100`                         | Public URL of the backend API                      |
-| `APP_URL`              | `http://localhost:3000`                         | Public URL of the dashboard                        |
-| `DOMAIN`               | `localhost`                                     | Cookie domain                                      |
-| `MONGODB_URI`          | `mongodb://mongo:27017/intlayer?replicaSet=rs0` | Full MongoDB connection URI                        |
-| `REDIS_URL`            | `redis://redis:6379`                            | Redis connection URL                               |
-| `BETTER_AUTH_SECRET`   | _(generated)_                                   | 32-byte secret for session signing                 |
-| `MAIL_PROVIDER`        | `smtp`                                          | Mail transport: `smtp` or `resend`                 |
-| `MAIL_SMTP_HOST`       | `mailpit`                                       | SMTP hostname (Mailpit container name)             |
-| `MAIL_SMTP_PORT`       | `1025`                                          | SMTP port                                          |
-| `MAIL_FROM`            | `Intlayer <no-reply@localhost>`                 | Sender address                                     |
-| `S3_ENDPOINT`          | `http://minio:9000`                             | S3-compatible endpoint                             |
-| `S3_PUBLIC_URL`        | `http://localhost:9000/intlayer`                | Public URL for browser asset loading               |
-| `S3_BUCKET_NAME`       | `intlayer`                                      | Bucket name                                        |
-| `S3_ACCESS_KEY_ID`     | _(generated)_                                   | MinIO access key                                   |
-| `S3_SECRET_ACCESS_KEY` | _(generated)_                                   | MinIO secret key                                   |
-| `VITE_BACKEND_URL`     | `http://localhost:3100`                         | Backend URL baked into the dashboard at build time |
-| `VITE_DOMAIN`          | `localhost`                                     | Domain baked into the dashboard at build time      |
+| 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)) |
+
+### 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.
+
+| 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.
 
 ### 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                         |
-| `RESEND_API_KEY`                                         | Transactional email via Resend (overrides Mailpit when set) |
-| `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                                       |
-| `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`           | LinkedIn OAuth login                                        |
-| `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`         | Atlassian 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-organisation 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).
 
-> Precedence: an organisation's own mailer (configured from the **Organisation** dashboard) takes priority over the global mailer, which in turn takes priority over the default Resend key.
+| 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.
 
 ## Connecting your Intlayer project
 
@@ -285,84 +527,17 @@ const cms = createIntlayerCMS({
 const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
 ```
 
-## Upgrading
-
-This pulls the latest images and restarts containers with `docker compose pull && docker compose up -d`. Existing volumes (`mongo-data`, `redis-data`, `minio-data`) are preserved — no data loss.
-
-```sh
-docker compose pull
-docker compose up -d
-```
-
-## Backup and restore
-
-All persistent data lives in three named Docker volumes.
-
-### Backup
-
-```sh
-docker run --rm \
-  -v intlayer_mongo-data:/data \
-  -v "$(pwd)":/backup \
-  busybox tar czf /backup/mongo-data.tar.gz /data
-
-docker run --rm \
-  -v intlayer_redis-data:/data \
-  -v "$(pwd)":/backup \
-  busybox tar czf /backup/redis-data.tar.gz /data
-
-docker run --rm \
-  -v intlayer_minio-data:/data \
-  -v "$(pwd)":/backup \
-  busybox tar czf /backup/minio-data.tar.gz /data
-```
-
-### Restore
-
-```sh
-docker run --rm \
-  -v intlayer_mongo-data:/data \
-  -v "$(pwd)":/backup \
-  busybox tar xzf /backup/mongo-data.tar.gz -C /
-
-# Repeat for redis-data and minio-data
-```
-
 ## 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.** 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`; serving it on a public domain would require rebuilding the image with the target URLs baked in 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 organisation can also configure its own SMTP or Resend mailer from the dashboard.
-
-## Troubleshooting
-
-### Backend crash-loops on first start
-
-MongoDB and Redis must be healthy before the backend starts. The compose file uses `depends_on` with `condition: service_healthy`. If you see repeated backend restarts, check that the `mongo` and `redis` healthchecks pass:
-
-```sh
-docker compose ps
-docker compose logs mongo
-docker compose logs redis
-```
-
-Look for `MongoDB connection error` near the top of the log.
-
-### Dashboard cannot reach the API
-
-Verify that `VITE_BACKEND_URL` matches the URL where the backend is reachable from the **browser** (not the Docker network). If you changed the backend port or added a reverse proxy, rebuild the dashboard image:
-
-### MinIO bucket missing
-
-If the `minio-init` one-shot service didn't run (or ran before MinIO was ready), create the bucket manually:
-
-```sh
-docker compose run --rm minio-init
-```
+- **No custom domain, and no port remapping.** 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. The dashboard must be accessed at `http://localhost:3000`, the API at `:3100` and MinIO at `:9000`. Serving it on a public domain, or pointing the desktop app at a self-hosted backend, requires rebuilding with the target URLs baked in (`--build-arg VITE_BACKEND_URL=… VITE_SITE_URL=… VITE_DOMAIN=…` on `docker/selfhost/Dockerfile`, or through `docker-compose.build.yml`) 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 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.
 
 ## Useful links
 
 - [Intlayer CMS documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
 - [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
-- [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)
-- [Docker Image (aymercizip/intlayer-selfhost)](https://hub.docker.com/repository/docker/aymercizip/intlayer-selfhost/general)
+- [CMS SDK: `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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`