> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nt3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting overview

> How an Entri instance is put together, what it needs to run, and how to choose between Docker Compose and Kubernetes.

Entri is open source (MIT) and runs on your own infrastructure. One container image serves the web app, the REST and GraphQL APIs, authentication, and the real-time progress channels. MongoDB stores your data and Redis handles caching and cross-process messaging.

> [!NOTE]
>
> The hosted service at app.nt3.io is being retired. If your organization has data there, see [Migrating from Entri Cloud](https://docs.nt3.io/self-hosting/migrating-from-cloud.md).

## Architecture

```text theme={null}
             browser / nt3 CLI / CI
                       │  HTTPS
              ┌────────▼────────┐
              │  reverse proxy  │  Caddy (Compose), an ingress controller (Kubernetes), or your own
              └────────┬────────┘
                       │  HTTP, WebSockets, Server-Sent Events
              ┌────────▼────────┐
              │      entri      │  ghcr.io/nt3-io/entri, port 3333
              │  SPA + API      │  /  /api/*  /graphql  /ws/progress
              └──┬──────┬────┬──┘
                 │      │    └──────────────► optional: Typesense or Algolia, SMTP or Resend,
        ┌────────▼──┐ ┌─▼─────┐                OpenAI / Anthropic, GitHub
        │  MongoDB  │ │ Redis │
        │ replica   │ │       │
        │   set     │ │       │
        └───────────┘ └───────┘
```

| Component | Required | Notes |
| - | - | - |
| **Entri** (`ghcr.io/nt3-io/entri`) | Yes | One image for amd64 and arm64. `serve` (default) starts the app on port 3333. `migrate` applies database migrations and exits. |
| **MongoDB 6+** | Yes | A **replica set** is the recommended default: Entri's auth layer uses multi-document transactions. A single-node replica set is fine, and so is MongoDB Atlas. A standalone `mongod` is supported with `MONGO_TRANSACTIONS=false`, with weaker guarantees on auth writes (sign-up and similar writes are no longer all-or-nothing). |
| **Redis 6+** | Yes | Short-lived cache (users, decrypted org AI keys, AI batch-job state, all with a TTL of about 5 minutes), distributed locks for GitHub sync, and pub/sub for import and translation progress. Nothing in Redis needs a backup. |
| **Search** | No | Without `SEARCH_PROVIDER`, search uses MongoDB queries. For larger projects you can use [Typesense](https://typesense.org) (bundled as an optional Compose profile) or Algolia. |
| **Email** | No, but recommended | SMTP or Resend, for invitations and password resets. Without it, emails go to the container log. |
| **AI providers** | No | OpenAI and Anthropic. Each organization can add its own keys in its settings. You can also set instance-wide fallback keys. |
| **GitHub App** | No | For [GitHub sync](https://docs.nt3.io/platform/features/github-integration.md). You register your own App: see [GitHub App setup](https://docs.nt3.io/platform/integrations/github-app-setup.md). |

All durable data lives in MongoDB. Back up MongoDB, plus the secrets in your configuration (see [Security](#security)).

## Requirements

> [tab] Docker Compose
>
> * A Linux host with Docker Engine 24+ and the Compose plugin
> * A DNS name pointing at the host (for HTTPS)
> * Ports 80 and 443 open, if you use the bundled Caddy proxy

> [tab] Kubernetes
>
> * Kubernetes 1.25+ and Helm 3.10+
> * An ingress controller (the chart documents ingress-nginx settings)
> * MongoDB 6+ (a replica set is recommended) and Redis 6+, either managed services or the chart's bundled single-pod StatefulSets

### Sizing

We do not publish benchmarks. These numbers are starting points, not limits:

* The Helm chart requests 250m CPU and 512 MiB of memory for Entri, with a 1 GiB memory limit. The bundled MongoDB requests 512 MiB (1 GiB limit) and the bundled Redis 64 MiB (256 MiB limit).
* For a small team on Docker Compose, a VM with 2 vCPUs and 4 GB of RAM leaves room for Entri, MongoDB, Redis and the operating system. Add memory if you enable Typesense, which keeps its index in RAM.
* MongoDB disk usage grows with the number of keys, languages, and the translation history. Watch it and grow the volume as needed. The chart's default volume is 8 GiB.

Large imports and AI batch translations are the heaviest operations. If you see memory pressure during them, raise the Entri memory limit first.

## Docker Compose or Kubernetes?

> [card] [Docker Compose](https://docs.nt3.io/self-hosting/docker.md)
>
> One VM, everything included: Entri, MongoDB, Redis, and optional Caddy (automatic HTTPS) and Typesense. The quickest path for most teams.

> [card] [Kubernetes (Helm)](https://docs.nt3.io/self-hosting/kubernetes.md)
>
> For teams that already run Kubernetes. Works with managed MongoDB and Redis. The chart can also bundle simple single-pod databases.

Both use the same image and the same [environment variables](https://docs.nt3.io/self-hosting/configuration.md).

> [!WARNING]
>
> Run **one** Entri replica unless your proxy has sticky sessions (cookie affinity). AI batch-translation progress streams are held in process memory. If a request lands on a different replica, its progress stream breaks.

## Security

* **The first account bootstraps the instance.** On an empty database, the first person to sign up can always create an account, even with `DISABLE_SIGNUP=true`. Sign up right after you deploy, or keep the instance unreachable until you have.
* **Close sign-up after that.** Set `DISABLE_SIGNUP=true` so only invited email addresses can create accounts. This covers email and password sign-up and social login. `GET /api/v1/config` reports the current state as `signupEnabled`.
* **Back up `ENCRYPTION_KEY`.** It encrypts organization AI keys (and cached GitHub installation tokens) at rest. If you lose it or change it, Entri cannot decrypt the stored keys, and every organization has to enter them again. Store it with your other secrets, separately from your database backups.
* **Keep `BETTER_AUTH_SECRET` stable.** It signs sessions. Changing it signs everyone out.
* **Proxy trust.** By default (`TRUST_PROXY` unset), Entri trusts `X-Forwarded-For` only from loopback, link-local and private-network peers. This covers a proxy in the same Compose network or an in-cluster ingress controller, and stops clients that connect directly from spoofing their IP address. The per-IP rate limiter depends on this. Set `TRUST_PROXY` only if the proxy in front of Entri has a public IP. See [Server settings](https://docs.nt3.io/self-hosting/configuration.md#server).
* **Instance-wide AI keys are shared.** `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` act as a fallback for every organization on the instance that has not set its own keys.
* **Databases are private.** The Compose file publishes no host ports for MongoDB or Redis, and both require a password. The Helm chart adds NetworkPolicies for its bundled databases.

## Next steps

> [card] [Deploy with Docker Compose](https://docs.nt3.io/self-hosting/docker.md)

> [card] [Deploy with Helm](https://docs.nt3.io/self-hosting/kubernetes.md)

> [card] [Configuration reference](https://docs.nt3.io/self-hosting/configuration.md)

> [card] [Upgrading](https://docs.nt3.io/self-hosting/upgrading.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.