// Deployment
Installing Fleeger from scratch
An end-to-end guide for a new operator standing up Fleeger on Kubernetes from the published charts and images — no repo checkout, no maintainer tooling. By the end you'll have the hub running, a first admin, the UI reachable, and one location (or a remote agent) reporting.
If you're the maintainer working from a git checkout, or you want the full reference for every value and Secret, see Deploying on Kubernetes instead — this guide is the short, opinionated path.
What you'll end up with
The fleeger-hub chart brings up, in one namespace: the dependencies (SurrealDB,
NATS/JetStream, VictoriaMetrics), the backend services (auth-svc,
inventory-svc, gateway-svc, ingestion-svc, alerting-svc, control-svc),
and the frontend SPA behind an edge that serves it and proxies /api to the
gateway. Service names are fixed, so install one hub release per namespace.
1. Prerequisites
- A Kubernetes cluster and a working
kubectlcontext. - Helm 3.14+ (3.8 for OCI chart support; 3.14 for the
--reset-then-reuse-valuesflag an upgrade that changes a value needs). - Pull access to the registry the release was published to
(
registry.example.com/fleegerin the examples below — substitute your host). If it's private, have animagePullSecretready in the namespace. dockeron your workstation for the one-time NATS auth generation in Step 3 (it runsnscinside a container — you don't installnscyourself).
Create the namespace you'll install into:
kubectl create namespace fleeger2. Create the credential master key Secret
Fleeger encrypts stored secrets (infra credentials, alert-channel configs) with a 32-byte master key. Generate one and store it as a Secret. Back it up — losing it makes every stored secret unrecoverable.
head -c 32 /dev/urandom | base64 | tr -d '\n' | \
kubectl -n fleeger create secret generic fleeger-credential-key --from-file=credential-key=/dev/stdin3. Generate and load the NATS auth material
Agents and services authenticate to NATS with decentralized (nsc) credentials.
This material can't be generated by the chart, so you produce it once and ship it
as a Secret. The generator is a small script; the easiest way to get it without a
full checkout is to grab it (and its siblings push-accounts.sh and
push-spokes.sh) from the release,
or clone just enough to run it:
# From a checkout of the release tag (only deploy/nats/ is needed):
deploy/nats/gen-auth.shThis writes gitignored material under deploy/nats/auth/. Regenerating rotates
all NATS credentials (every agent must
re-onboard), so do it once and keep the
output safe. See agent credentials for the
trust model.
Ship it as the Secret the chart expects (fleeger-nats-auth):
kubectl -n fleeger create secret generic fleeger-nats-auth \
--from-file=ingestion.creds=deploy/nats/auth/ingestion.creds \
--from-file=gateway.creds=deploy/nats/auth/gateway.creds \
--from-file=alerting.creds=deploy/nats/auth/alerting.creds \
--from-file=inventory.creds=deploy/nats/auth/inventory.creds \
--from-file=control.creds=deploy/nats/auth/control.creds \
--from-file=core-agent.creds=deploy/nats/auth/core-agent.creds \
--from-file=sys.creds=deploy/nats/auth/sys.creds \
--from-file=operator.nk=deploy/nats/auth/operator.nk \
--from-file=spokes-account.nk=deploy/nats/auth/spokes-account.nk \
--from-file=resolver.conf=deploy/nats/auth/resolver.conf \
--from-file=SPOKES.jwt=deploy/nats/auth/nsc-data/nats/nsc/stores/fleeger/accounts/SPOKES/SPOKES.jwtInclude every key above. Each is referenced by name in a pod's volume
projection, so a missing one doesn't degrade — that pod crash-loops (or, for
core-agent.creds, hangs in ContainerCreating with nothing in the logs).
core-agent.creds is only read when coreAgent.enabled=true, but including it
now is free and saves a broken install later. The chart preflights the Secret on
helm install/upgrade and fails with the missing key names.
Optional Secrets
The chart generates strong values for the SurrealDB root password and the
internal service token on install and keeps them across upgrades, so you don't
have to (with helm install/upgrade; under Argo CD or helm template the
chart cannot read the cluster, refuses, and names the existingSecret values to
set, see the Helm chart reference, section GitOps). To pin your own instead, create Secrets with db-password /
internal-token keys and pass --set surrealdb.existingSecret=… /
--set internal.existingSecret=…. If you enable scheduled backups you'll also
provide an S3 credential Secret — see
backup & restore.
4. Install the hub from the OCI registry
helm install fleeger oci://registry.example.com/fleeger/charts/fleeger-hub \
--version 1.0.0-rc1 \
--namespace fleeger \
--set image.registry=registry.example.com/fleeger \
--set 'imagePullSecrets[0].name=<your-pull-secret>' \
--set credential.existingSecret=fleeger-credential-keyDrop the imagePullSecrets line if the registry is public. Leave image.tag
unset: the chart runs the images its own release published (its appVersion),
so upgrading the chart later upgrades the images with it. A tag set here would
be stored in the release and carried into every upgrade. Watch it settle:
kubectl -n fleeger get pods -wThe DB-owning services run migrations in an init container (retried until SurrealDB is up) and a one-off Job pushes the SPOKES account into the NATS resolver; the services go Ready shortly after.
Bringing your own identity provider? Disable the bundled
auth-svcwith--set services.auth-svc.enabled=falseand front the gateway with your OIDC provider. Any core service can be toggled the same way when you supply that capability yourself.
5. Bootstrap the first admin
There's no self-registration; an operator creates the first admin with the
auth-svc admin CLI, run inside its pod:
kubectl -n fleeger exec -it deploy/auth-svc -- /usr/local/bin/service \
user add -u admin -e admin@example.com -r admin # prompts for the passwordIt prompts for the password without echoing it, so the password never appears
in a process list (-p would put it in the kubectl and container command
lines, which any local user can read). The command is journalled in the
audit log before the user is created, so run it once inventory-svc is up
(its init container migrates the audit database); before that it refuses and
creates nothing. Additional users can be added the same
way with -r operator or -r viewer, or from the UI later.
6. Reach the UI
Expose the edge and open it, then sign in with the admin you just created (see logging in).
The flags below go on the helm install in
step 4. The hub is already
installed by now, so to add them to it, put them on
helm upgrade fleeger oci://registry.example.com/fleeger/charts/fleeger-hub --namespace fleeger --reset-then-reuse-values
(with --version set to the chart version you are running) instead: an
upgrade that passes values without that flag resets everything else you set at
install, including the image and credential settings above.
Ingress (needs a controller): add these flags to the
helm installin step 4 (ending its last line with\), then open the host.--set ingress.enabled=true \ --set ingress.host=fleeger.example.com \ --set 'edge.trustedProxies[0]=<ingress-controller-pod-CIDR>'Replace
<ingress-controller-pod-CIDR>with the address range of the one hop directly in front of the edge, usually your ingress controller's pod CIDR. An unreplaced placeholder, or any entry that is not an IPv4/IPv6 address or CIDR, stops the install before anything is applied, with an error naming the entry. Without the flag at all the install stops the same way, with an error sayingedge.trustedProxiesis empty. The Kubernetes deployment guide explains how to find the right range and why only that hop may be trusted.NodePort:
--set edge.service.type=NodePort --set edge.service.nodePort=30080→http://<node-ip>:30080.Quick check:
kubectl -n fleeger port-forward svc/edge 8080:80→ open http://localhost:8080.
Enable TLS before exposing it past a trusted LAN — the login sends credentials and agents connect over WebSocket. The Kubernetes deployment guide has the cert-manager values block.
7. Onboard the first location (or a remote agent)
With the hub up you can start collecting:
A location reachable from the hub — create it in inventory, add a resource, then onboard its agent. Follow onboarding a location end to end.
A remote agent at another site — install the published
fleeger-agentchart there, pointed at your hub with a one-time registration token. Paste the token at the prompt; it is not echoed and stays off every command line:printf 'Registration token: '; stty -echo; IFS= read -r FLEEGER_TOKEN; stty echo; echo printf '%s' "$FLEEGER_TOKEN" | kubectl create secret generic fleeger-agent-token \ --from-file=registration-token=/dev/stdin unset FLEEGER_TOKEN helm install fleeger-agent oci://registry.example.com/fleeger/charts/fleeger-agent \ --version 1.0.0-rc1 \ --set image.repository=registry.example.com/fleeger/spoke-agent \ --set hub.url=https://fleeger.example.com \ --set existingSecret=fleeger-agent-tokenThe token comes from Onboard in the UI; the agent bootstraps once with it, receives location-scoped NATS credentials, and starts reporting. See onboarding a location.
Within ~30s the location flips to reachable on the dashboard.
Next steps
- Logging in and managing users & roles.
- Onboarding a location for every additional site.
- Deploying on Kubernetes for TLS, network segmentation, upgrades, key rotation, and the full values reference.
- Backup & disaster recovery.