@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.20

package/docs/en/releases/v9.md

@@ -1,15 +1,19 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-07-08
 title: New Intlayer v9 - What's new?
-description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections, Variants, and Dynamic Records.
+description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries, support for Collections and Variants, self-hosting via Docker Compose, and the new @intlayer/analytics package for content A/B testing.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
+  - CMS SDK
+  - Self-Hosting
+  - Docker
+  - Analytics
+  - A/B Testing
   - i18next
   - next-intl
   - vue-i18n
@@ -17,12 +21,16 @@ slugs:
   - doc
   - releases
   - v9
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Add @intlayer/analytics: page/locale + content-exposure tracking, A/B testing, and the dashboard Analytics page"
 author: aymericzip
 ---
 
 # New Intlayer v9 - What's new?
 
-Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections**, **Variants**, and **Dynamic Records**.
+Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.), adds support for rich content structures (**Collections** and **Variants**), and introduces **`@intlayer/analytics`** to track content exposure and run A/B tests.
 
 ## Table of contents
 
@@ -41,8 +49,10 @@ By replacing imports, you get all the benefits of Intlayer (including compile-ti
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 For example, simply change:
 
@@ -100,42 +110,56 @@ All compat adapters now route translation resolution through a single, highly op
 
 ---
 
-## Feature Spec: Collections, Variants & Dynamic Records
+## Feature Spec: Collections & Variants
 
 Intlayer v9 expands beyond static key-value objects, allowing dictionaries to declare dynamic layout structures that are fully typed end-to-end.
 
 ### 1. Collections
 
-Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists):
+Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists). Each item lives in its own `.content.ts` file with the same `key` and an `item` number:
 
-```ts fileName="faq.content.ts"
+```ts fileName="faq.1.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "faq",
-  content: [
-    {
-      question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
-      answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
-    },
-  ],
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
+
+```ts fileName="faq.2.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
 } satisfies Dictionary;
 ```
 
 #### Usage:
 
 ```ts
-// Fetch all items
+// Fetch all items as an array
 const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
 
-// Fetch single item by index
-const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
 ```
 
 ### 2. Variants
 
 Deliver A/B tests, seasonal headers, feature flags, or custom landing pages:
 
+#### String variants (e.g. A/B testing)
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -155,16 +179,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. Dynamic Records
-
-Define dictionaries whose entries are loaded dynamically at runtime via query IDs:
+#### Object variants (e.g. Dynamic Records)
 
 ```ts fileName="product.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "product-copy",
-  meta: {
+  variant: {
     id: "prod_123",
     category: "books",
   },
@@ -177,30 +199,171 @@ export default {
 #### Usage:
 
 ```ts
-// Fetches only the requested item dynamically (requires Suspense)
+// Fetches only the requested record dynamically (requires Suspense)
 const product = useIntlayer("product-copy", {
-  id: "prod_123",
-  category: "books",
+  variant: { id: "prod_123", category: "books" },
 });
 ```
 
 ---
 
-## Dynamic Loading & Bundle Size Optimizations
+## `@intlayer/analytics`: content exposure tracking & A/B testing
+
+A new optional package, [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md), tells you which content is actually shown to your visitors — and closes the loop on **Collections & Variants** by letting you A/B test content and measure conversions per variant.
+
+- **Provider-level tracking**: `IntlayerProvider` (React / Next.js / React Native) automatically records `page_view` events on load, route change, and locale change.
+- **Node-level tracking**: every `useIntlayer` resolution reports a `content_exposure` event — which dictionary key, key path, locale, and (when applicable) A/B **variant** was displayed. Repeated exposures within a flush window are coalesced.
+- **Deterministic A/B assignment**: `getVariant(experimentKey, variants)` assigns each session to a variant with **no server round-trip**, so there is no flicker before first render.
+- **`useConversion()`**: attribute a goal (signup, click, purchase…) to the variant a session was exposed to.
+- **Zero cost when not installed**: same tree-shakeable pattern as `@intlayer/editor` — dynamic `import()` wrapped in `try/catch`, plus a compile-time env var (`INTLAYER_ANALYTICS_ENABLED`) that dead-code-eliminates the whole integration for apps that don't opt in.
+- **No new config schema**: reuses `editor.backendURL` (ingestion endpoint / self-hosting) and `editor.clientId` (project key, also the enable switch).
+- **Privacy-respecting**: anonymous session hashing (SHA-256, no raw ids stored), no IP storage, coarse country-only geolocation, batched requests roughly every 20 seconds.
+- **Dashboard**: a new **Analytics** page (shown in the sidebar once a project is selected) reports active users, users today, users over the last 7/30/90 days, a visitor evolution graph, and Locales vs. Location breakdowns.
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
+};
+```
 
-To keep bundles extremely small, Intlayer v9 supports dynamic lazy loading.
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+Available today for React, Next.js, and React Native (via `react-intlayer`); other framework bindings (Vue, Svelte, Angular, …) are planned, following the same rollout pattern as `@intlayer/editor`. See the [Analytics documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) for the full guide.
+
+---
 
-In your configuration, set `importMode` to `'dynamic'` or `'fetch'`:
+## Vite Plugin: Bundled Compiler & Proxy
+
+The `intlayer()` Vite plugin now bundles the **compiler** and the **locale-routing proxy** directly, so most projects only need a single plugin in `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: Activates automatically when `compiler.enabled` is set to `true` and a `compiler.output` path is configured. You no longer need to register `intlayerCompiler()` separately.
+- **Proxy**: Activates automatically based on the new `routing.enableProxy` option (`true` by default). It wires the locale detection / redirect / rewrite middleware in development, preview, and production SSR. You no longer need to register `intlayerProxy()` separately.
+
+### `routing.enableProxy` option
+
+A new `routing.enableProxy` option controls whether the locale-routing proxy is plugged in. It defaults to `true`. Disable it when you want to handle locale routing yourself:
 
 ```ts fileName="intlayer.config.ts"
-export default {
-  dictionary: {
-    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // Default: true
   },
 };
+
+export default config;
+```
+
+The standalone `intlayerCompiler()` and `intlayerProxy()` plugins remain exported for advanced setups. Registering them alongside `intlayer()` is safe — each plugin deduplicates itself and runs only once.
+
+---
+
+## Compiler disabled by default
+
+Starting with Intlayer v9, the **compiler is disabled by default** (`compiler.enabled` now defaults to `false`). To opt in to build-time extraction of your `.content.ts` files, set `compiler.enabled: true` in your configuration:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Default: false — required to enable the compiler since v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+When the compiler is disabled, Intlayer skips the build-time extraction step and relies on your already-declared dictionaries. Enable it only when you want the bundler plugin (`@intlayer/swc`, `@intlayer/babel`, or the `intlayer()` Vite plugin) to extract content automatically.
+
+---
+
+## React Native: single-package imports
+
+In a React Native or Expo app, you no longer need to juggle both `react-intlayer` and `react-native-intlayer`. The `react-native-intlayer` package now **re-exports the full `react-intlayer` API** (hooks, utilities, and the `/format`, `/html`, and `/markdown` subpaths), and its `IntlayerProvider` automatically applies the React Native polyfills.
+
+Import everything from the single `react-native-intlayer` package:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Importing from `react-intlayer` keeps working, but `react-native-intlayer` is now the recommended single entry point for React Native — its provider ships the polyfills the web-oriented `react-intlayer` provider does not.
+
+---
+
+## CMS SDK: use Intlayer as a headless content database
+
+Intlayer v9 ships a clean, auto-authenticating SDK in `@intlayer/api` to interact with the CMS programmatically — fetch projects, fetch dictionaries, and push or update them from your own server, scripts, or CI. Authentication (OAuth2 `client_credentials`) is handled and refreshed for you.
+
+The SDK is split into **two separate imports** so your bundle includes only the domains you actually use:
+
+1. `createIntlayerCMS` — a lightweight **authenticator** holding the credentials and the managed token (no domain client bundled).
+2. `dictionaryEndpoint`, `projectEndpoint`, … — per-domain **endpoint binders**, each imported from its own subpath.
+
+```ts fileName="cms.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS();
+
+// Read
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+
+// Write — use the CMS like a database
+await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
+```
+
+> Security: the CMS credentials grant write access to your content. Only ever create the authenticator on the **server side** — never ship `clientId` / `clientSecret` to the browser.
+
+---
+
+## Self-Hosting
+
+Intlayer v9 ships first-class support for running your own Intlayer instance with a single command. No Intlayer Cloud account required.
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
 ```
 
-At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace `useIntlayer` / `getIntlayer` calls with tree-shakeable wrappers (`useDictionary` / `useDictionaryDynamic`). Only the content required for the selected collection item, variant, or locale is loaded, preventing your production bundle from containing unused translations.
+The installer downloads a `docker-compose.yml` and a `.env`, auto-generates the required secrets, and runs `docker compose up -d`. Everything — the dashboard, the API, the database, object storage, and transactional email — runs locally in containers.
 
 ---
 
@@ -208,13 +371,20 @@ At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
 
+- **Compiler disabled by default**: `compiler.enabled` now defaults to `false`. If you rely on build-time extraction of your `.content.ts` files, set `compiler.enabled: true` in your `intlayer.config.ts`.
+- **Vite plugin**: The compiler and locale-routing proxy are now bundled into `intlayer()`. If you previously registered `intlayerCompiler()` or `intlayerProxy()` manually, you can remove them — they are deduplicated automatically, so keeping them is harmless. Use `routing.enableProxy: false` to opt out of the proxy.
 - **Locales & Dialects**: If using external i18n dependencies, add their respective compat adapter plugins in your configuration or bundler setup to automatically rewrite imports.
-- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant, id }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+- **React Native**: `react-native-intlayer` now re-exports the entire `react-intlayer` API. In a React Native app, import everything from `react-native-intlayer` and drop the direct `react-intlayer` dependency. Existing `react-intlayer` imports continue to work.
 
 ---
 
 ## Useful links
 
 - [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
-- [Dynamic Dictionaries - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Analytics - Content exposure tracking & A/B testing](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [React Native & Expo Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_react_native+expo.md)
+- [CMS SDK - Programmatic access with @intlayer/api](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md)

package/docs/en/self_hosting.md

@@ -0,0 +1,310 @@
+---
+createdAt: 2026-06-30
+updatedAt: 2026-07-02
+title: Self-Hosting Intlayer
+description: Run a complete Intlayer instance on your own infrastructure with a single container. No Intlayer Cloud account required.
+keywords:
+  - Self-Hosting
+  - Docker
+  - Intlayer
+  - CMS
+  - Installation
+  - Infrastructure
+slugs:
+  - doc
+  - self-hosting
+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).
+
+The only external dependency is **MongoDB**: the backend connects to a MongoDB **Atlas** cluster, which you provide. Everything else runs inside the container.
+
+## Table of Contents
+
+<TOC/>
+
+---
+
+## Architecture
+
+```
+                ┌─────────────────────────────┐
+ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
+ (localhost)    └─────────────────────────────┘   │ VITE_BACKEND_URL (baked at build)
+                ┌─────────────────────────────┐   │
+                │  backend (Fastify/Bun)  :3100│ ◀─┘
+                └──────────────┬──────────────┘
+          ┌──────────┬─────────┼───────────────────────┐
+          ▼          ▼         ▼                        ▼
+       redis:6379  minio:9000  Chromium            MongoDB Atlas
+       (bundled)   (S3 API)    (in-image)          (external, via DB_*)
+                   minio:9001
+                   (console)
+```
+
+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://`.
+
+---
+
+## Prerequisites
+
+- **Docker** ≥ 24.
+- 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).
+
+---
+
+## Quick start
+
+Pull and run the published image, supplying your MongoDB Atlas credentials and secrets:
+
+```sh
+docker run -d --name intlayer \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  -e DB_ID="<atlas-user>" \
+  -e DB_MDP="<atlas-password>" \
+  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
+  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
+  -e RESEND_API_KEY="<your-resend-key>" \
+  aymericzip/intlayer-selfhost
+```
+
+Then open **http://localhost:3000**.
+
+> The dashboard is served on `localhost`. See [Limitations](#limitations) — custom domains are not supported by the published image.
+
+---
+
+## 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.
+3. Click the link in the email, then sign in.
+
+Once an admin exists, `/init` redirects to the standard sign-in page.
+
+---
+
+## Services
+
+| 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` |
+
+> 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`.
+
+---
+
+## Environment variables
+
+### 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)) |
+
+### 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                     |
+
+### 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                     |
+
+### 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.
+
+Set `MAIL_PROVIDER` to activate it. When unset, the default Resend mailer is used.
+
+| 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                                                     |
+
+> 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
+
+Once the stack is running, point your project at the self-hosted backend and dashboard instead of `intlayer.org`.
+
+### Project configuration
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * URL of the self-hosted CMS dashboard.
+     * Default: https://app.intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL, // e.g. http://localhost:3000
+
+    /**
+     * URL of the self-hosted backend API.
+     * Default: https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL, // e.g. http://localhost:3100
+  },
+};
+
+export default config;
+```
+
+Set the environment variables in your project's `.env`:
+
+```sh
+INTLAYER_CMS_URL=http://localhost:3000
+INTLAYER_BACKEND_URL=http://localhost:3100
+INTLAYER_CLIENT_ID=<your-client-id>
+INTLAYER_CLIENT_SECRET=<your-client-secret>
+```
+
+Create access credentials in your self-hosted dashboard under **Projects → Access keys** at `http://localhost:3000/projects`.
+
+### `@intlayer/api` SDK
+
+When using the `@intlayer/api` SDK programmatically, pass `backendURL` explicitly:
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
+  },
+});
+
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+```
+
+---
+
+## Upgrading
+
+Pull the latest image and recreate the container. Your data is preserved in the named volume (MinIO/Redis) and in your Atlas cluster (MongoDB):
+
+```sh
+docker pull aymericzip/intlayer-selfhost
+docker stop intlayer && docker rm intlayer
+# re-run the `docker run …` command from 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.** 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 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: check that `DB_ID`, `DB_MDP`, and `DB_CLUSTER` are set and correct.
+
+```sh
+docker logs intlayer
+```
+
+Look for `MongoDB connection error` near the top of the log.
+
+### 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
+```
+
+---
+
+## 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)
+- [Docker Image (aymercizip/intlayer-selfhost)](https://hub.docker.com/repository/docker/aymercizip/intlayer-selfhost/general)

package/docs/en-GB/CI_CD.md

@@ -26,6 +26,10 @@ author: aymericzip
 
 Intlayer allows the automatic generation of translations for your content declaration files. There are multiple ways to achieve this depending on your workflow.
 
+## Table of Contents
+
+<TOC/>
+
 ## Using the CMS
 
 With Intlayer, you can adopt a workflow where only a single locale is declared locally, while all translations are managed remotely through the CMS. This allows content and translations to be completely detached from the codebase, offering more flexibility for content editors and enabling hot content reloading (no need to rebuild the application to apply changes).