# Self-host Kuery

Deployment prerequisites, verification, and recovery for Kuery.

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


## Prerequisites

You need a Kubernetes runtime you administer, Helm, network access from the provider runtime to the hub and advertised virtual-workspace endpoints, and permission to onboard this provider. Use the [common provider flow](https://railgrid.ai/docs/self-hosting/providers/) to obtain the workspace kubeconfig. The examples below use a Secret named `railgrid-provider-kubeconfig` with data key `kubeconfig`.

For production, a Postgres database and its connection string.

## Install

```bash
kubectl create namespace railgrid-provider-kuery
kubectl --namespace railgrid-provider-kuery create secret generic railgrid-provider-kubeconfig \
  --from-file=kubeconfig=./kuery.kubeconfig
```

`kuery-values.yaml` with Postgres:

```yaml
replicaCount: 2
hub:
  url: https://railgrid-hub.railgrid-system.svc.cluster.local:9443
  tokenSecretRef:
    name: ""
catalogEntry:
  enabled: true
store:
  driver: postgres
  persistence:
    enabled: false
  # dsn: set at install time, not in this file
```

The chart has no Secret reference for the DSN; `store.dsn` is a plain value. Keep it out of committed values files: pass it on the command line from a Secret, or, with Flux, inject it with `valuesFrom` from a Secret key into `store.dsn`.

```bash
helm upgrade --install kuery oci://ghcr.io/railgrid/charts/railgrid-kuery-provider --version CHART_VERSION \
  --namespace railgrid-provider-kuery --values kuery-values.yaml \
  --set-string store.dsn="$(kubectl -n railgrid-provider-kuery get secret kuery-dsn -o jsonpath='{.data.dsn}' | base64 -d)"
```

The chart README contains the matching values table for the deployed version: [chart instructions](https://github.com/railgrid/railgrid/blob/main/providers/kuery/deploy/chart/README.md).

## Provider requirements

SQLite on the chart's PVC is the default and pins the provider to one replica; it is not a multi-replica production store. With `store.driver: postgres`, extra replicas buy availability: every replica serves queries, MCP, and the portal from the shared store, while the sync controllers are singletons behind a Lease in the provider workspace. Size resources for the number of engaged edges; the sync engine holds informer caches for every one. Review `sync.whitelist` and `sync.blacklist` before enabling inventory sync, since edge links are often bandwidth-constrained.

Postgres over a private network with `sslmode=require` in the DSN is what Railgrid runs; the database is the provider's only state.

## Verify

Run `kubectl -n railgrid-provider-kuery get pods` and wait for Ready and a fresh heartbeat. A fresh provider stays unready until a workspace enables it; see [the common flow](https://railgrid.ai/docs/self-hosting/providers/#a-fresh-provider-is-unready-until-a-workspace-binds-it). Enable Kuery in a test workspace, connect a disposable edge, and verify engagement, whitelist behavior, and synchronization using the [Kuery quickstart](https://railgrid.ai/docs/use/kuery/quickstart/).

## Recover

For a failed rollout, preserve the SQLite PVC or Postgres data before changing storage settings. Inspect edge engagement and sync logs, restore the original driver/DSN, and verify one edge's inventory before expanding the fleet.

## Configuration reference

[Chart values](https://github.com/railgrid/railgrid/blob/main/providers/kuery/deploy/chart/values.yaml) are authoritative for this source baseline. Keep the deployed image and chart versions recorded together.