# Catalox deployment

Embedder, CLI, private HTTP, and (later) public Authix. Env: [`environment.md`](./environment.md). Roadmap: [`catalox-v6/README.md`](./catalox-v6/README.md).

## Modes

| Mode | Artifact | Network | Auth | When |
|------|----------|---------|------|------|
| **Embedder** | `@x12i/catalox` / engine | In-process | Host → `CataloxContext` | BFFs, workers |
| **CLI** | `catalox` bin | Outbound to Mongo (+ R2) | Service creds | Seed, ops |
| **Private HTTP** | `catalox-service` | Internal only | `CATALOX_AUTH_MODE=open` | Internal services (5.9.x+) |
| **Public HTTP** | same + Authix | HTTPS public | `authix` Bearer | **6.1.0** |
| **Fixtures** | `LocalFileStore` | None | File ACL | Tests only |

## Prerequisites

| Need | Notes |
|------|-------|
| Node `>=20` | |
| **`MONGO_URI`** | Primary persistence (DB default `catalox`) |
| R2 / `S3_*` | Record history / backup after 6.0.0 object cutover |
| Google SA | **Migration only** — `mongo import-from-firestore` |
| Authix | Production public API (**6.1.0**) |

## 1) Library embedder

```bash
npm install @x12i/catalox
```

```ts
import { createCataloxFromEnv } from "@x12i/catalox/mongo";

const { catalox } = await createCataloxFromEnv({
  mongoUri: process.env.MONGO_URI,
});
```

→ [`mongo-persistence.md`](./mongo-persistence.md)

## 2) CLI

```bash
export MONGO_URI=...
npx catalox mongo probe
npx catalox items list --app <appId> --catalog <catalogId>
```

→ [`onboarding-happy-path.md`](./onboarding-happy-path.md)

## 3) Private HTTP (`catalox-service`)

```bash
export MONGO_URI=...
export CATALOX_AUTH_MODE=open
export CATALOX_PRIVATE_MODE=true
# optional: CATALOX_DEFAULT_SUPER_ADMIN=true  (never on a public URL)
```

Bind ClusterIP / private network only. Client: `withContext` + `X-Catalox-Context`.

→ [`packages/http/catalox-service/README.md`](../packages/http/catalox-service/README.md) · [`catalox-v6/5.9.5/README.md`](./catalox-v6/5.9.5/README.md)

**Critical:** `open` + `superAdmin` must never be reachable from the public internet.

## 4) Public production API (6.1.0 + Authix)

Do this only after [`6.0.0/checklist.md`](./catalox-v6/6.0.0/checklist.md).

| Variable | Value |
|----------|--------|
| `CATALOX_AUTH_MODE` | `authix` |
| `AUTHIX_APP_ID` / `AUTHIX_APP_SECRET_KEY` | Required |
| `AUTHIX_INTROSPECT_URL` | Required for writes |
| `CATALOX_CORS_ORIGINS` | Browser allowlist |
| `MONGO_URI` + R2 | From 6.0.0 |

Checklist: [`catalox-v6/6.1.0/checklist.md`](./catalox-v6/6.1.0/checklist.md)  
Contract: [`catalox-v6/6.1.0/README.md`](./catalox-v6/6.1.0/README.md)

## Storage migration (6.0.0)

Firestore/GCS estates → Mongo + R2: [`catalox-v6/6.0.0/transition-from-5.10.md`](./catalox-v6/6.0.0/transition-from-5.10.md).