--- url: https://docs.fluxify.rest/deployments.md description: >- Overview and decision guide for self-hosting Fluxify. Choose between the all-in-one Kit image for quick trials and the scale-out Admin + Workers topology for production, with shared setup steps and secret key generation. --- # Self-Hosting Fluxify Fluxify is built to run on your own infrastructure. There are **two ways** to deploy it, and this page helps you pick the right one and points you to the exact steps for each. > \[!TIP] > New to how Fluxify works internally? The [Architecture](/architecture/) section > explains the control plane / worker split that both setups below are built on. > \[!WARNING] > **Alpha software.** Fluxify is in active alpha development. It is suitable for > self-hosted trials and early production use, but internal schemas may change > between versions — read the release notes before upgrading. *** ## The two ways to run Fluxify | | **Kit** (all-in-one) | **Admin + Workers** (scale-out) | | :--- | :--- | :--- | | **Best for** | Prototypes and testing only | Production, on one Docker host or Kubernetes | | **Containers** | One — database, cache and event bus included | Separate admin + many workers | | **Scaling** | Vertical only (bigger machine) | Horizontal — add workers on demand | | **Edge proxy** | Built into the image | Traefik (load-balances the workers) | | **Setup effort** | Lowest — one command | Moderate | | **Guide** | [Quick Run with the Kit Image →](./kit) | [Production Setup →](./production) | ### Which should I choose? * **Prototyping or testing?** Use the **Kit**, and only for that: never for production. It bundles every service into a single container and starts with one command. → [Quick Run guide](./kit) * **Anything in production**, even on a single machine? Use **Admin + Workers**. The control plane runs once; stateless workers scale horizontally behind Traefik. The workers run on either: * **Docker**: one host, a fixed number of workers per claim. → [Production guide](./production) * **Kubernetes**: your cluster, with workers that grow and shrink with load. → [Install on Kubernetes](./kubernetes/install) > \[!TIP] > Start with the Kit to evaluate, then move to Admin + Workers when you need to > scale — your `.env` and database carry straight over. > \[!TIP] > **Let a coding agent do it.** Claude Code, Cursor or Codex can deploy either > setup from these docs. See [Deploy with a Coding Agent](./coding-agent) for > copy-paste prompts and a checklist to check its work. *** ## How the pieces fit together Both topologies share the same three backing services and the same URL layout — they differ only in how the application containers are split up. **Kit — everything in one container:** ```mermaid flowchart TB C(["Client"]) --> K subgraph K["Kit container :8080"] direction LR WEB["Web dashboard"] ADM["Admin API
+ compiler"] WRK["Request worker"] AI["AI gateway"] BS["PostgreSQL · Valkey · NATS
(bundled, or bring your own)"] end style C fill:#111113,stroke:#EF4444,color:#FAFAFA style K fill:#111113,stroke:#D2FF4D,color:#FAFAFA style BS fill:#111113,stroke:#F59E0B,color:#FAFAFA ``` **Admin + Workers — control plane split from a worker pool:** ```mermaid flowchart TB C(["Client"]) --> T["Traefik :80"] T -->|"/_/admin*"| A["Admin container
dashboard · admin API
compiler · AI gateway"] T -->|"/*"| W1["Worker"] & W2["Worker"] & W3["Worker"] A --> DB[("PostgreSQL")] A --> BUS["NATS"] BUS --> W1 & W2 & W3 A --> R["Valkey"] W1 & W2 & W3 --> R style C fill:#111113,stroke:#EF4444,color:#FAFAFA style A fill:#111113,stroke:#D2FF4D,color:#FAFAFA style W1 fill:#111113,stroke:#10B981,color:#FAFAFA style W2 fill:#111113,stroke:#10B981,color:#FAFAFA style W3 fill:#111113,stroke:#10B981,color:#FAFAFA ``` Notice that only the admin container reaches PostgreSQL. Workers receive your routes ready to run over NATS, so they never need database access — see [Request Lifecycle](/architecture/request-lifecycle). ### Backing services (both setups) | Service | Role | | :--- | :--- | | **PostgreSQL** | Stores workflows, project configuration, and user accounts. Only the admin container connects to it. | | **Valkey / Redis** | Caching and fast lookups. | | **NATS** | Delivers compiled routes to workers and keeps live configuration in sync. | > \[!WARNING] > **NATS must be started with JetStream enabled** (`-js` on the command line). > Fluxify uses it to queue compile work and to store the compiled routes that > workers pull. Without it the compiler will not start and your workers will > have nothing to serve. The bundled compose files already set this. ### URL layout (both setups) | Path | Serves | | :--- | :--- | | `/_/admin/ui` | Web dashboard (visual editor) | | `/_/admin/api` | Admin REST API | | `/_/admin/api/openapi/ui` | API documentation | | `/_/admin/mcp` | MCP server for AI apps and coding agents | | `/.well-known/oauth-…` | Sign-in details for MCP clients | | `/` | Your published workflows and custom endpoints | > \[!NOTE] > **Namespace isolation.** Everything under `/_/admin` is platform management and > the visual editor. The rest of the root path `/` is reserved for the endpoints > you build in Fluxify, so your APIs never collide with the admin surface. The > one exception is `/.well-known/oauth-…`, which MCP clients need for sign-in. *** ## System requirements | Resource | Kit (trial) | Admin + Workers (production) | | :--- | :--- | :--- | | **CPU** | 1 core | 2+ cores (plus ~1 core per worker) | | **RAM** | 2 GB | 4 GB+ | | **Disk** | 5 GB | 20 GB+ SSD | | **Docker** | Engine 20.10+ / Desktop | Engine 20.10+ | *** ## Generate your secret keys Both setups need the same secrets in their `.env`. Generate them once here, then follow the guide for your chosen setup: * `MASTER_ENCRYPTION_KEY` — encrypts stored credentials. * `BETTER_AUTH_SECRET` — signs authentication sessions. > \[!WARNING] > Back up `MASTER_ENCRYPTION_KEY`. If you lose or change it after storing data, > every saved credential becomes permanently unreadable. > \[!IMPORTANT] > **Admin and workers must share the same `MASTER_ENCRYPTION_KEY`.** Project > configuration reaches workers encrypted with it; a worker with a different key > starts up and then fails every request. A worker refuses to start without one. ### One more setting: which project a worker serves A request worker serves either exactly **one** project, named by `WORKER_PROJECT_ID`, or every project with `*`. You get a project id from the project's settings page in the dashboard. The production guides create the project first, then pin a worker group to its id. The Kit defaults to `*`, so it serves routes from the first boot without an id to copy. To serve several projects with a pinned worker, run a separate group of workers for each. Copies of the same worker share their settings, so they always share a project. ::: tip Serving every project from one worker Set `WORKER_PROJECT_ID` to `*` (the Kit's default) and the worker serves every project you have, picking up new ones as you create them — no restart, no id to copy. Good for a personal install or a staging box. Give each project its own subdomain (**Project settings → General**) and two projects can use the same route path without clashing: `shop.example.com/orders` and `blog.example.com/orders` reach different projects. Projects without a subdomain share the bare domain, where a path used by two of them resolves to only one. The base domain is set in **Instance settings → Hosting**. A slow project still slows the rest, since they share one worker. ::: *** ## Next steps Pick your path and jump straight to the steps: * **Kit:** [run one command](./kit#bundled) → [turn on the request worker](./kit#worker) * **Admin + Workers:** [why Traefik](./production#why-traefik) → [create your `.env`](./production#env) → [start the stack](./production#start) → [scale the workers](./production#scaling) * **With a coding agent:** [pick a prompt](./coding-agent#prompts) → [check its work](./coding-agent#checklist) * **On Kubernetes:** [install step by step](./kubernetes/install) → [what it creates](./kubernetes/#objects) → [size and scale workers](./kubernetes/#sizing)