Kubernetes — Caby

For most Kubernetes-based setups, we recommend deploying with our official Helm Chart. This page will walk you through how to deploy using Helm or plain Kubernetes manifests.

Helm

Caby’s OCI chart is published to GHCR with every release, versioned to match the Caby release it ships:

oci://ghcr.io/caby-io/charts/caby

Prerequisites

Before starting, ensure that you have:

A Kubernetes cluster,
Helm 3, and
kubectl

Steps

Create Caby’s configuration file. See the config file page for the full reference. Here’s a minimal example with one space (home) and one user for our first deployment:
config.yaml
```
spaces:
  - name: home
    display: "🏠 Home"
users:
  - name: YOUR_USERNAME
    # a unique 64-character token for first-time login
    activation_token: REPLACE_WITH_A_UNIQUE_64_CHARACTER_TOKEN
    spaces:
      - name: home
        permissions: "*"
```
Save this as config.yaml:
- config.yaml
There are a few ways to load this configuration into Caby. One easy way is with a Kubernetes Secret. Create a namespace (caby) and a Secret with our config from earlier:
Terminal window
```
kubectl create namespace caby

kubectl create secret generic caby-config \
  --from-file=config.yaml=./config.yaml \
  -n caby
```
Determine which Helm values you need for your setup. At a minimum you must provide a valid ingress.web.host or disable the ingress with ingress.enabled set to false.

If you’ve followed the previous steps you should have a Secret in the same namespace as the deployment and can set it in your chart with config.existingSecret:
Terminal window
```
helm install caby oci://ghcr.io/caby-io/charts/caby \
  --version 0.2.1 \
  --namespace caby \
  --set ingress.web.host=files.my-domain.com \
  --set config.existingSecret=caby-config
```
Watch the deployments come up:
Terminal window
```
kubectl -n caby get deployments -w
```
Once both deployments are ready, navigate to the activation page (e.g. https://files.my-domain.com/activate).

Values reference

The values below cover the most common setup. For everything the chart supports, see values.yaml.

Key	Default	Description
`ingress.enabled`	`true`	Create an Ingress for the frontend/backend. Set to `false` to bring your own.
`ingress.web.host`	N/A	Public hostname. Sets the web & API URL across the app (e.g. `example.caby.com`). Required if you enable the ingress.
`config.existingSecret`	`""`	Bring your own config Secret (sealed-secrets, external-secrets, …).
`config.inline`	starter config	Rendered into a Secret unless `config.existingSecret` is set.
`ingress.api.host`	`""`	Set to a distinct host for two-host mode; empty = single host, API on `/api`.
`ingress.tls`	`true`	Serve over https.
`ingress.tlsSecretName`	`""`	Falls back to `<release>-tls` when empty. Needed for setups such as wildcard certs.
`persistence.size`	`20Gi`	Backend data PVC size.
`persistence.existingClaim`	`""`	Reuse an existing PVC instead of provisioning one.
`backend.secretEnv`	`{}`	Map of secret env (e.g. OIDC client secret).

kubectl

For vanilla Kubernetes deployments you can generate plain manifests from the Helm chart.

Prerequisites

Before starting, ensure that you have:

A Kubernetes cluster,
Helm 3 (used to generate manifests until we have standalones), and
kubectl

Steps

Create Caby’s configuration file. See the config file page for the full reference. Here’s a minimal example with one space (home) and one user for our first deployment:

spaces:
  - name: home
    display: "🏠 Home"
users:
  - name: YOUR_USERNAME
    # a unique 64-character token for first-time login
    activation_token: REPLACE_WITH_A_UNIQUE_64_CHARACTER_TOKEN
    spaces:
      - name: home
        permissions: "*"

Save this as config.yaml:

config.yaml

Create a namespace (caby) and a Secret with the config from the previous step:

kubectl create namespace caby

kubectl create secret generic caby-config \
  --from-file=config.yaml=./config.yaml \
  -n caby

Render the chart to plain manifests. The same values apply, so at a minimum provide a valid ingress.web.host and point config.existingSecret at the Secret you just created:
Terminal window
```
helm template caby oci://ghcr.io/caby-io/charts/caby \
  --version 0.2.1 \
  --namespace caby \
  --set ingress.web.host=files.my-domain.com \
  --set config.existingSecret=caby-config \
  > caby.yaml
```
You should now have this file saved alongside config.yaml:
- caby.yaml
- config.yaml
Apply the manifests to the caby namespace:
Terminal window
```
kubectl apply -n caby -f caby.yaml
```
Watch the deployments come up:
Terminal window
```
kubectl -n caby get deployments -w
```
Once both deployments are ready, navigate to the activation page (e.g. https://files.my-domain.com/activate).