# Install Berth, binary, Docker & Helm quickstart

> Step-by-step Berth install for any level: run the binary, run the Docker image with your kubeconfig mounted, or install the Helm chart. Prereqs, licensing, verification and troubleshooting.

Berth ships as a single container (or a single binary). Pick the way that fits you, all three end with the dashboard on `http://localhost:8081`. No prior Berth knowledge needed.

## How it works

Berth is one process: a web UI baked into a small Go binary that talks to the Kubernetes API. It runs in one of two modes:

- `remotecluster`, talks to a cluster using your local `~/.kube/config`. Best for trying it on your laptop (the **binary** and **Docker** methods).
- `incluster`, runs as a pod and uses its ServiceAccount. This is what the **Helm** chart deploys.

**Viewing is always free, no key needed.** A license key only unlocks *changes* (create/edit/delete). Grab a free Community key any time from your [account](https://berth.agrohi.com/login/), see [Apply your key](#apply-your-license-key).

## Prerequisites

- A Kubernetes cluster you can reach. Anything works, a cloud cluster, or local `kind`/`minikube`/`k3d`.
- `kubectl` configured for it. Check with `kubectl get nodes`, if that lists nodes, you're set.
- For the Helm method: [Helm 3.8+](https://helm.sh/docs/intro/install/). For Docker: any recent Docker/Podman.
- *Optional:* `metrics-server` for CPU/memory graphs. Berth degrades gracefully without it.

## 1 · Run the binary

The fastest way to look at a cluster. One file, no install, uses your kubeconfig.

1. **Download** the build for your OS and architecture from the [downloads page](https://berth.agrohi.com/download/). Or pull it from the command line (Linux x86-64 shown):
   ```
   curl -sSLO https://github.com/unishsys/berth/releases/latest/download/berth-linux-amd64
   curl -sSLO https://github.com/unishsys/berth/releases/latest/download/SHA256SUMS
   ```
2. **Verify and make it executable.** The checksum step is optional but recommended.
   ```
   shasum -a 256 -c SHA256SUMS --ignore-missing   # optional integrity check
   chmod +x berth-linux-amd64
   ```
   macOS may quarantine the download, clear it with `xattr -d com.apple.quarantine berth-darwin-*`.
3. **Run it** against your current kubeconfig context, then open the dashboard.
   ```
   export AUTH_TOKEN="$(openssl rand -hex 32)"
   ./berth-linux-amd64 remotecluster
   # now open http://localhost:8081
   ```
   Token authentication is the default, including on loopback. Use a random token of at least 32 characters and enter it in the dashboard. It stays in this tab’s session storage when available. Closing the tab clears it; blocked storage also clears it on reload.

## 2 · Run with Docker

Same as the binary, but containerized, mount your kubeconfig read-only and Berth uses it.

1. **Run the signed image** with your kubeconfig mounted at the location the nonroot user expects:
   ```
   export AUTH_TOKEN="$(openssl rand -hex 32)"
   docker run --rm -p 127.0.0.1:8081:8081 \
     -e AUTH_TOKEN -e AUTH_MODE=token -e BIND_ADDRESS=0.0.0.0 \
     -v "$HOME/.kube/config:/home/nonroot/.kube/config:ro" \
     ghcr.io/unishsys/berth:latest remotecluster
   # open http://localhost:8081
   ```

   **Cluster reachable from the container?** If your kubeconfig points at `127.0.0.1` (common with `kind`/`minikube`), add `--network host` (Linux) or use the host gateway so the container can reach the API server.

2. **Verify the image** (optional). Images are cosign-signed with GitHub OIDC, no keys to manage:
   ```
   cosign verify ghcr.io/unishsys/berth:latest \
     --certificate-identity-regexp 'https://github.com/unishsys/.*' \
     --certificate-oidc-issuer https://token.actions.githubusercontent.com
   ```

## 3 · Install with Helm

The production path: deploys Berth *inside* the cluster with RBAC and a generated auth token. The chart is an OCI artifact on GHCR.

1. **Install the chart** into a `berth` namespace. `upgrade --install` is idempotent, the same command installs the first time and upgrades after:
   ```
   helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth \
     --namespace berth --create-namespace
   ```
   Already have a key? Apply it in the same step by adding `--set license.key='<YOUR_KEY>'` (see [Apply your key](#apply-your-license-key)). `--version` pins a reproducible install; omit it to take the latest stable.
2. **Read the auth token** the chart generated (token auth is the secure default):
   ```
   kubectl -n berth get secret berth-secrets \
     -o jsonpath='{.data.AUTH_TOKEN}' | base64 -d ; echo
   ```
3. **Open it** via a port-forward (or set up an Ingress, see [below](#expose-it-on-a-hostname-optional)):
   ```
   kubectl -n berth port-forward svc/berth 8081:8081
   # open http://localhost:8081 and paste the token
   ```

## Apply your license key

Berth is free to view. To **make changes**, add a license key: a free **Community** key (up to 10 nodes) or an **Enterprise** key (node allowance agreed for your deployment). Get yours from your [license account](https://berth.agrohi.com/login/), it's verified offline, so it works in air-gapped clusters.

### Helm

```
helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth --reuse-values \
  --namespace berth \
  --set license.key='<YOUR_KEY>'
```

### Binary or Docker

Set it as an environment variable:

```
LICENSE_KEY='<YOUR_KEY>' export AUTH_TOKEN="$(openssl rand -hex 32)"
   ./berth-linux-amd64 remotecluster
# Docker: add  -e LICENSE_KEY='<YOUR_KEY>'  to the docker run command
```

Logged-in users get copy-paste commands with the key already filled in on the [in-app guide](https://berth.agrohi.com/guide/).

## Verify it works

Open the dashboard, the license banner should show your tier and node cap, and Create/Edit actions are enabled once a key is applied. From the command line:

```
curl -s http://localhost:8081/api/v1/license \
  -H "Authorization: Bearer <AUTH_TOKEN>"
# token authentication is the default for every installation
```

## Expose it on a hostname (optional)

For a Helm install, turn on the Ingress and TLS instead of port-forwarding:

```
helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth --reuse-values \
  --namespace berth \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=berth.your-domain.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=berth-tls
```

Berth has cluster-wide access, treat dashboard access as cluster access. Never run `AUTH_MODE=none` on a shared or exposed cluster, and always serve it over HTTPS.

## Troubleshooting

- **"Binary exits immediately."** It needs a mode: run `remotecluster` (laptop) or `incluster` (pod).
- **CPU/memory graphs are blank.** Your cluster has no `metrics-server`. Everything else still works.
- **Gateways / certificates show "not installed."** Those CRDs (Gateway API, cert-manager) aren't present, expected, Berth degrades gracefully.
- **401 from the API.** `AUTH_MODE=token` is on but no token was sent. Read it from the `berth-secrets` Secret (Helm step 2).
- **Docker can't reach the cluster.** Your kubeconfig points at `127.0.0.1`; add `--network host` or use the host gateway.

Need more than the Community node cap? [See Enterprise](https://berth.agrohi.com/pricing/). Prefer to grab a build first? [Download Berth](https://berth.agrohi.com/download/).

The chart uses one replica, Recreate updates and persistent local RWO storage. Review storage classes and existing Helm overrides when upgrading.