# Self-hosting

Install, configure, operate, and upgrade the hub and providers.

Source: https://railgrid.ai/docs/self-hosting/


Use the Railgrid SaaS hub to get started without operating the control plane. If you want to run Railgrid on your own infrastructure, choose the software you need to run:

- [Install a hub](https://railgrid.ai/docs/self-hosting/hub/helm/): embedded kcp for a single-replica installation, or [external kcp](https://railgrid.ai/docs/self-hosting/hub/external-kcp/) for a highly available control plane you operate separately.
- [Self-host an existing provider](https://railgrid.ai/docs/self-hosting/providers/): connect your runtime to an existing hub.

Managing users on a running hub belongs in [Administration](https://railgrid.ai/docs/administration/). Building a new provider belongs in [Extend Railgrid](https://railgrid.ai/docs/extend/).

## Two deployment shapes

These pages describe what Railgrid itself runs. Both shapes use the same charts and the same providers; they differ in how traffic reaches the hub and where state lives.

| | Small cluster | Cloud cluster |
|---|---|---|
| Kubernetes | A single-node or small k3s cluster | A managed cluster (GKE in the examples) |
| Public entry | [Cloudflare Tunnel](https://railgrid.ai/docs/self-hosting/hub/cloudflare-tunnel/), no inbound ports | [Gateway API](https://railgrid.ai/docs/self-hosting/hub/gateway-api/) on a cloud load balancer, DNS-only records |
| TLS at the edge | Cloudflare Universal SSL | Cloud-managed wildcard certificates |
| kcp | External, one etcd member per shard | External, three etcd members per shard across zones |
| Provider databases | Postgres in the cluster | Managed Postgres |
| Object storage | MinIO in the cluster | Cloud object storage through its S3 API |
| Dex state | Postgres | Kubernetes resources |

Both shapes run Dex for OIDC, two hub replicas against external kcp, and the public providers from the `oci://ghcr.io/railgrid/charts` registry, reconciled by Flux.

## Bring-up order

Install the layers in this order, verifying each before the next. Every later layer depends on an earlier one being reachable.

1. Public entry: DNS, certificates, and the [ingress](https://railgrid.ai/docs/self-hosting/hub/ingress/) that will carry every hostname.
2. cert-manager, and the kcp-operator if you run [external kcp](https://railgrid.ai/docs/self-hosting/hub/external-kcp/).
3. kcp: etcd, shards, and the front proxy.
4. [Dex](https://railgrid.ai/docs/self-hosting/hub/oidc/), reachable at its public issuer URL.
5. The [hub](https://railgrid.ai/docs/self-hosting/hub/helm/).
6. [Providers](https://railgrid.ai/docs/self-hosting/providers/), one namespace each.

Before production use, establish a [storage and recovery procedure](https://railgrid.ai/docs/self-hosting/hub/operations/) and record the deployed component versions. Source examples are not a certification of a production deployment.


## In this section

- [Hub deployment](https://railgrid.ai/docs/self-hosting/hub/): Install, configure, secure, and operate a self-hosted Railgrid hub.
- [Self-host an existing provider](https://railgrid.ai/docs/self-hosting/providers/): Run a capability on your infrastructure and connect it to a hub.