Quick Start¶

Get Velero Dashboard running in under 10 minutes!

Prerequisites¶

Before you begin, ensure you have:

Python 3.13+ installed
Access to Kubernetes clusters with Velero installed
Kubeconfig files or service account tokens for cluster access
(Optional) OIDC Provider like Dex, Keycloak, or Auth0

Option 1: Local Development (Fastest)¶

1. Clone and Install¶

# Clone the repository
git clone https://github.com/yourusername/velero-dashboard.git
cd velero-dashboard

# Install dependencies
pip install -r requirements.txt

2. Configure Clusters¶

Create config/clusters.yaml:

clusters:
  - name: my-cluster
    description: My Kubernetes Cluster
    environment: development
    api_server: https://kubernetes.default.svc
    auth_method: kubeconfig
    kubeconfig_path: ~/.kube/config
    is_active: true

3. Configure Permissions¶

Create config/casbin_policy.csv:

# Grant admin access to yourself
g, your-username, velero.admin

# Admin role can do everything
p, velero.admin, *, *, .*

4. Set Environment Variables¶

export SECRET_KEY=$(python -c 'import secrets; print(secrets.token_hex(32))')
export FLASK_ENV=development
export FLASK_DEBUG=True

# For development without OIDC:
export OIDC_DISCOVERY_URL=http://localhost:5556/dex
export OIDC_CLIENT_ID=velerodashboard
export OIDC_CLIENT_SECRET=dev-secret

5. Run the Application¶

python app.py

Visit http://localhost:8000

Development Mode

In development mode without a real OIDC provider, you may see authentication errors. For full functionality, configure Dex (see below) or use another OIDC provider.

Option 2: Docker (Recommended)¶

1. Pull or Build Image¶

# Option A: Build locally
docker build -t velerodashboard:latest .

# Option B: Pull from registry (if published)
docker pull your-registry/velerodashboard:latest

2. Prepare Configuration¶

Create a directory for configs:

mkdir -p ./config

Create ./config/clusters.yaml and ./config/casbin_policy.csv as shown above.

3. Run Container¶

docker run -d \
  --name velerodashboard \
  -p 8000:8000 \
  -e SECRET_KEY="your-secret-key-here" \
  -e OIDC_CLIENT_ID="velerodashboard" \
  -e OIDC_CLIENT_SECRET="your-oidc-secret" \
  -e OIDC_DISCOVERY_URL="http://localhost:5556/dex" \
  -v $(pwd)/config:/app/config:ro \
  -v ~/.kube:/root/.kube:ro \
  velerodashboard:latest

Access the dashboard at http://localhost:8000

Option 3: Kubernetes with Helm (Production)¶

1. Add Helm Repository¶

# If you've published to a Helm repository
helm repo add velerodashboard https://your-registry/chartrepo/velerodashboard
helm repo update

2. Create Values File¶

Create values-prod.yaml:

global:
  domain: velerodash.example.com

dashboard:
  replicaCount: 2

  config:
    oidc:
      clientId: velerodashboard
      clientSecret: your-oidc-secret-from-keyvault
      discoveryUrl: https://dex.example.com/dex

    clusters:
      - name: prod-cluster-1
        description: Production Cluster 1
        environment: production
        api_server: https://k8s-prod-1.example.com
        auth_method: token
        token: "your-service-account-token"
        is_active: true

  ingress:
    enabled: true
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    tls:
      - secretName: velerodash-tls
        hosts:
          - velerodash.example.com

dex:
  enabled: true
  config:
    issuer: https://dex.example.com/dex
    staticClients:
      - id: velerodashboard
        name: Velero Dashboard
        secret: your-oidc-secret-from-keyvault
        redirectURIs:
          - https://velerodash.example.com/callback

3. Install¶

helm install velerodashboard ./helm/velerodashboard \
  -f values-prod.yaml \
  --namespace velero-dashboard \
  --create-namespace

4. Verify Installation¶

kubectl get pods -n velero-dashboard
kubectl get ingress -n velero-dashboard

Setting Up Dex (Optional but Recommended)¶

If you don't have an OIDC provider, use the bundled Dex:

1. Configure Dex¶

Edit helm/velerodashboard/values.yaml:

dex:
  enabled: true
  config:
    staticPasswords:
      - email: admin@example.com
        password: $2y$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W  # "password"
        username: admin
        userID: 08a8684b-db88-4b73-90a9-3cd1661f5466

2. Generate Password Hash¶

# Install bcrypt tool
pip install bcrypt

# Generate hash
python -c "import bcrypt; print(bcrypt.hashpw(b'your-password', bcrypt.gensalt()).decode())"

Navigate to your dashboard URL
Click "Login with OIDC"
Enter your credentials (Dex static user or your OIDC provider credentials)
You'll be redirected to the dashboard

First-Time Setup

Make sure you've added your username to the Casbin policy file before logging in, otherwise you won't have any permissions!

Next Steps¶

Now that you're up and running:

Troubleshooting¶

Cannot Connect to Cluster¶

Problem: "Failed to connect to cluster" error

Solutions: - Verify kubeconfig path is correct - Check API server URL is reachable - Ensure service account token has proper permissions - Verify Velero is installed in the cluster

OIDC Authentication Fails¶

Problem: Authentication redirects fail or timeout

Solutions: - Check OIDC_DISCOVERY_URL is correct and reachable - Verify redirect URI matches in OIDC provider config - Enable Dex proxy if having CORS issues: USE_DEX_PROXY=True - Check logs: docker logs velerodashboard or kubectl logs -n velero-dashboard

Problem: "Access Denied" on all pages

Solutions: - Check your username in Casbin policy file - Verify policy file syntax is correct - Check file watcher is working (logs should show "Policy file changed") - Ensure you're using the correct username (check profile page)

For more help, see the Troubleshooting Guide.