Skip to main content

Getting Started

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

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/v1beta2
kind: OCIRepository
metadata:
  name: gyre
  namespace: flux-system
spec:
  interval: 1h
  url: oci://ghcr.io/entropy0120/charts/gyre
  ref:
    semver: '>=0.1.0'
---
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.5.0 \
  --namespace flux-system \
  --create-namespace
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.

docker run \
    -e AUTH_ENCRYPTION_KEY=$(openssl rand -hex 32) \
    -e GYRE_ENCRYPTION_KEY=$(openssl rand -hex 32) \
    -e ADMIN_PASSWORD=admin123 \
    -v gyre-data:/data \
    -v ~/.kube/config:/app/.kube/config:ro \
    -p 3000:3000 \
    ghcr.io/entropy0120/gyre:latest
tip

Change ADMIN_PASSWORD to a strong password before use. The AUTH_ENCRYPTION_KEY and GYRE_ENCRYPTION_KEY values are used to encrypt session data and secrets — regenerate them with openssl rand -hex 32 each time you deploy.

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:

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

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