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

# Kubernetes & OpenShift

> Deploy Fossa on Kubernetes or OpenShift with the official Helm charts.

Prefer a cluster over a single VM? Fossa ships configuration and deployment assets for Kubernetes and
OpenShift in the [fossa repository](https://github.com/brittytino/fossa). This page is the overview
for cluster deployments (air-gapped installs, ExternalSecrets, operators,
observability, and SOC 2-oriented hardening).

## Requirements

* Helm 3.8+
* Kubernetes 1.28+ or OpenShift 4.14+
* For `mode: operator` data stores, the matching operator installed on the cluster

## Quick start (bundled data stores)

The default `bundled` mode runs PostgreSQL (pgvector), MongoDB, and RabbitMQ as
StatefulSets the chart manages — the equivalent of Docker Compose `USE_LOCAL_DB=true`.
One command, no operators:

```bash theme={null}
git clone https://github.com/brittytino/fossa.git
cd fossa
helm dependency build
helm install fossa . -n fossa --create-namespace \
  --set imageTag=<version> \
  --set global.config.WEB_HOSTNAME_API=api.fossa.example.com \
  --set global.config.NEXTAUTH_URL=https://fossa.example.com \
  --set ingress.hosts.web.host=fossa.example.com \
  --set ingress.hosts.api.host=api.fossa.example.com
```

`imageTag` pins the Fossa release for the whole stack (like Docker Compose
`IMAGE_TAG`); use a real tag, never `latest`, in production. Auth/crypto secrets
are generated automatically with the correct format and stay stable across
upgrades.

<Tip>
  The webhooks service needs its own public host. Point `ingress.hosts.webhooks.host`
  (or `route.hosts.webhooks.host` on OpenShift) at a dedicated hostname and the chart
  auto-derives `API_<provider>_CODE_MANAGEMENT_WEBHOOK` for you.
</Tip>

## Data store modes

Each store (`postgres`, `mongodb`, `rabbitmq`) has an independent `mode`:

| mode | what it does | for |
| - | - | - |
| `bundled` *(default)* | a StatefulSet managed by the chart | dev / trials |
| `external` | your managed/self-managed service via an `existingSecret` | production |
| `operator` | a CR reconciled by a cluster operator (HA) — CloudNativePG, RabbitMQ Cluster Operator, MongoDB Community Operator | production |

For production, prefer `external` or `operator` — they hand database operation to
something purpose-built.

## OpenShift

Add the OpenShift overlay — Routes replace Ingress, and pod UIDs are left to the
namespace SCC (`restricted-v2`), so no UIDs are hardcoded:

```bash theme={null}
helm install fossa . -f values.yaml -f values-openshift.yaml \
  -n fossa --create-namespace --set imageTag=<version>
```

Leave `route.hosts.*.host` empty to let OpenShift auto-assign the
`<name>-<namespace>.apps…` hostname. Note that some clusters mirror or block
Docker Hub `library/*` images, so the bundled `mongo` image may need an override
(`--set mongodb.bundled.image=mirror.gcr.io/library/mongo:8`) or an `external` /
`operator` data store.

## Optional services & verification

* **MCP manager** — `--set services.mcp-manager.enabled=true`
* **Analytics worker** — `--set services.worker-analytics.enabled=true`
* **Health check** — `../../scripts/doctor-k8s.sh -n fossa` inspects workloads, config,
  and the real health endpoints.

<Card title="Fossa Repository" icon="github" href="https://github.com/brittytino/fossa">
  Data-store operator setup, reusing existing databases, air-gapped installs,
  secrets via ExternalSecrets, observability, and security defaults.
</Card>


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