Skip to main content

Getting Started

This guide will help you get Gyre up and running in your Kubernetes cluster.

Production installs are Helm/GitOps-first and in-cluster. Local out-of-cluster usage is for development/testing.

Prerequisites​

Before you begin, ensure you have:

  • Kubernetes cluster (1.24+)
  • Helm 3.x installed
  • FluxCD installed in your cluster
  • kubectl configured to access your cluster

Installation​

Gyre can be installed in several ways depending on your workflow.

Option 1: GitOps (Using FluxCD)​

The most natural way to install Gyre is by using Flux itself. Add this HelmRelease to your GitOps repository:

---
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: gyre
  namespace: flux-system
spec:
  interval: 1h
  url: oci://ghcr.io/entropy0120/charts/gyre
  ref:
    tag: 0.8.0-rc.2
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: gyre
  namespace: flux-system
spec:
  interval: 1h
  chartRef:
    kind: OCIRepository
    name: gyre
    namespace: flux-system

Option 2: Helm​

The standard way to install Gyre directly via Helm:

helm install gyre oci://ghcr.io/entropy0120/charts/gyre \
  --version 0.8.0-rc.2 \
  --namespace flux-system \
  --create-namespace

The chart generates the encryption and metrics Secrets on first install and retains them across upgrades and uninstall. For production, you can provide externally managed Secrets through encryption.existingSecret and metrics.existingSecret.

note

OCI Helm registries require an explicit version. Check the latest release for the current version number.

Option 3: Local Out-of-Cluster Testing (Docker)​

If you want to try the UI without installing it inside your cluster, you can run it locally connected to your kubeconfig. Make sure your current Kubernetes context points to a cluster with Flux installed.

# Run once per environment. Keep this file for future container recreations.
if [ ! -f .env.gyre ]; then
    (umask 077; {
        echo "AUTH_ENCRYPTION_KEY=$(openssl rand -hex 32)"
        echo "GYRE_ENCRYPTION_KEY=$(openssl rand -hex 32)"
        echo "BACKUP_ENCRYPTION_KEY=$(openssl rand -hex 32)"
        echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)"
        echo "GYRE_METRICS_TOKEN=$(openssl rand -hex 32)"
    } > .env.gyre)
fi

docker run \
    --env-file .env.gyre \
    -v gyre-data:/data \
    -v ~/.kube/config:/app/.kube/config:ro \
    -p 3000:3000 \
    ghcr.io/entropy0120/gyre:latest
tip

The production image requires GYRE_METRICS_TOKEN to protect /metrics. Omit ADMIN_PASSWORD to let Gyre generate one, or provide a strong password that satisfies the app password policy. Store .env.gyre securely and back it up with the gyre-data volume. Reuse it whenever you recreate the container; rotate data-encryption keys only with a migration plan to avoid making existing data unreadable.

Option 4: Local Demo Script​

Don't have a cluster yet? Spin up a local kind cluster with Flux and Gyre pre-installed using our demo script (it creates required Helm secrets automatically):

curl -sL https://raw.githubusercontent.com/entropy0120/gyre/main/scripts/demo.sh | bash

If you are developing from a local checkout, prefer:

./scripts/demo.sh

Accessing Gyre​

Port Forward (Development)​

kubectl port-forward -n flux-system svc/gyre 3000:80

Then open http://localhost:3000

Production Access (Ingress / LoadBalancer)​

For production deployments, you should use an Ingress Controller or a LoadBalancer service. See the Production Access & Ingress Guide for detailed configuration examples for Nginx, Traefik, and more.

First Login​

  1. Get the initial admin password:

    kubectl get secret gyre-initial-admin-secret \
      -n flux-system \
      -o jsonpath='{.data.password}' | base64 -d

  2. Open Gyre in your browser

  3. Login with:

    • Username: admin
    • Password: (from step 1)

  4. Change the password immediately after first login

Next Steps​

Troubleshooting​

If you encounter issues:

  1. Check pod status:

    kubectl get pods -n flux-system -l app.kubernetes.io/name=gyre

  2. View logs:

    kubectl logs -n flux-system -l app.kubernetes.io/name=gyre

  3. Check our Troubleshooting guide