Kubernetes Deployment Guide

This comprehensive guide explains how to deploy Kaneo on Kubernetes using our official Helm chart. This setup is ideal for production environments where you need scalability, high availability, and enterprise-grade infrastructure.

Prerequisites

Before you begin, ensure you have:

Kubernetes cluster (v1.19 or higher)
Helm 3 installed and configured
kubectl configured to communicate with your cluster
Basic knowledge of Kubernetes and Helm concepts
Ingress controller (nginx, traefik, etc.) for production deployments

Quick Installation

Clone the Kaneo repository

git clone https://github.com/usekaneo/kaneo.git
cd kaneo

Install with default configuration

helm install kaneo ./charts/kaneo --namespace kaneo --create-namespace

This will deploy Kaneo with PostgreSQL and default settings.

Access your deployment

Use port forwarding to access the services locally:

# Port forward to access both services
kubectl port-forward svc/kaneo-web 5173:5173 -n kaneo &
kubectl port-forward svc/kaneo-api 1337:1337 -n kaneo &
 
# Access the application at http://localhost:5173

Production Deployment with Ingress

For production environments, you should expose Kaneo through an Ingress controller:

Create a production values file

Create a file named kaneo-values.yaml with production-ready configuration:

# PostgreSQL configuration
postgresql:
  auth:
    password: "your-secure-db-password"
  persistence:
    size: 20Gi
    storageClass: "managed-premium"
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi
 
# API configuration
api:
  env:
    jwtAccess: "your-secure-jwt-token"
 
  # For production, consider setting resource limits
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 256Mi
 
# Web configuration
web:
  env:
    apiUrl: "https://your-domain.com"
 
  resources:
    limits:
      cpu: 300m
      memory: 256Mi
    requests:
      cpu: 100m
      memory: 128Mi
 
ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/rewrite-target: /$1
  hosts:
    - host: your-domain.com
      paths:
        - path: /?(.*)
          pathType: Prefix
          service: web
          port: 80
        - path: /api/?(.*)
          pathType: Prefix
          service: api
          port: 1337
  tls:
    - secretName: kaneo-tls
      hosts:
        - your-domain.com

Deploy with custom configuration

helm install kaneo ./charts/kaneo \
  --namespace kaneo \
  --create-namespace \
  -f kaneo-values.yaml

Configure DNS

Configure your DNS settings to point your-domain.com to your Ingress controller's external IP or load balancer.

Verify deployment

You should now be able to access Kaneo at https://your-domain.com and the API will be accessible at https://your-domain.com/api. 🎉

Using Secrets for Sensitive Data

For better security, you can store sensitive data like JWT tokens and database credentials in Kubernetes Secrets:

Create secrets

kubectl create secret generic kaneo-secrets \
  --namespace kaneo \
  --from-literal=jwt-access="your-secure-jwt-token" \
  --from-literal=postgres-password="your-secure-db-password"

Update values to use secrets

postgresql:
  auth:
    existingSecret: "kaneo-secrets"
    secretKeys:
      userPasswordKey: "postgres-password"
 
api:
  env:
    existingSecret:
      enabled: true
      name: "kaneo-secrets"
      key: "jwt-access"

Upgrade your deployment

helm upgrade kaneo ./charts/kaneo \
  --namespace kaneo \
  -f kaneo-values.yaml

Using External PostgreSQL Database

If you prefer to use an external PostgreSQL database instead of the bundled one:

Configure external database

Update your values file to disable the bundled PostgreSQL and configure external database:

# Disable bundled PostgreSQL
postgresql:
  enabled: false
 
api:
  env:
    jwtAccess: "your-secure-jwt-token"
    database:
      external:
        enabled: true
        host: "your-postgres-host.com"
        port: 5432
        database: "kaneo"
        username: "kaneo_user"
        password: "your-db-password"

Deploy or upgrade

helm upgrade --install kaneo ./charts/kaneo \
  --namespace kaneo \
  --create-namespace \
  -f kaneo-values.yaml

Using Gateway API

As an alternative to Ingress, you can use the Kubernetes Gateway API for more advanced routing capabilities:

Verify Gateway API installation

Make sure the Gateway API is installed in your cluster.

Create Gateway configuration

Create a file named kaneo-gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: kaneo
  namespace: kaneo
spec:
  parentRefs:
  - name: main-gateway  # Your gateway name
    namespace: gateway-system  # Your gateway namespace
    sectionName: https
  hostnames:
  - "your-domain.com"
  rules:
  # Frontend route (root path)
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: kaneo-web
      port: 80
  # API route (api path prefix)
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: kaneo-api
      port: 1337
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /

Apply the configuration

kubectl apply -f kaneo-gateway.yaml

Database Management

Backup and Recovery

For production deployments, consider implementing regular database backups:

# Example backup command
kubectl exec -it deployment/kaneo-postgresql -- pg_dump -U kaneo_user kaneo > kaneo-backup.sql

Migration from SQLite

If you're migrating from a previous SQLite-based installation, you'll need to:

Export your data from SQLite
Deploy the new PostgreSQL-based chart
Import your data into PostgreSQL

Contact the Kaneo community on Discord for migration assistance.

Uninstalling

To uninstall Kaneo from your Kubernetes cluster:

helm uninstall kaneo -n kaneo

This will remove all the Kubernetes components associated with the chart and delete the release.

Next Steps

Configure monitoring with Prometheus and Grafana
Set up automated backups for your PostgreSQL database
Implement horizontal pod autoscaling for high availability

Kubernetes Deployment Guide

On this page