Deploy nfyio on Kubernetes with Helm Charts

Running nfyio on Kubernetes gives you horizontal scaling, automated rollouts, and self-healing infrastructure. This guide walks you through deploying the full nfyio stack using Helm charts.

Prerequisites

• Kubernetes cluster (1.27+) — EKS, GKE, AKS, or self-managed
• kubectl configured to your cluster
• helm v3.12+
• A domain pointed to your cluster’s ingress IP
• At least 3 nodes with 4 vCPU / 8 GB RAM each

Verify your tools:

kubectl version --client
helm version
kubectl get nodes

Add the nfyio Helm Repository

helm repo add nfyio https://charts.nfyio.com
helm repo update

List available charts:

helm search repo nfyio

NAME                    CHART VERSION   APP VERSION   DESCRIPTION
nfyio/nfyio             0.9.0           0.9.0         nfyio cloud infrastructure platform
nfyio/seaweedfs         3.67.0          3.67          SeaweedFS distributed storage
nfyio/keycloak          22.0.0          22.0.4        Keycloak identity and access management

Create the Namespace and Secrets

kubectl create namespace nfyio

# Database credentials
kubectl create secret generic nfyio-db \
  --namespace nfyio \
  --from-literal=POSTGRES_USER=nfyio \
  --from-literal=POSTGRES_PASSWORD=$(openssl rand -base64 32) \
  --from-literal=POSTGRES_DB=nfyio

# JWT signing key
kubectl create secret generic nfyio-jwt \
  --namespace nfyio \
  --from-literal=JWT_SECRET=$(openssl rand -base64 64)

# OpenAI API key (for embeddings)
kubectl create secret generic nfyio-ai \
  --namespace nfyio \
  --from-literal=OPENAI_API_KEY=sk-your-key-here

# Keycloak admin
kubectl create secret generic keycloak-admin \
  --namespace nfyio \
  --from-literal=KEYCLOAK_ADMIN=admin \
  --from-literal=KEYCLOAK_ADMIN_PASSWORD=$(openssl rand -base64 24)

Create the Values File

Create values-production.yaml:

# values-production.yaml
global:
  domain: nfyio.example.com
  storageClass: gp3

gateway:
  replicas: 3
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: "2"
      memory: 2Gi
  env:
    NODE_ENV: production
    LOG_LEVEL: info
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
    targetCPU: 70

storage:
  replicas: 2
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: "2"
      memory: 4Gi

agents:
  replicas: 2
  resources:
    requests:
      cpu: "1"
      memory: 2Gi
    limits:
      cpu: "4"
      memory: 8Gi
  env:
    EMBEDDING_MODEL: text-embedding-3-small
    EMBEDDING_DIMENSIONS: 1536

postgresql:
  enabled: true
  primary:
    persistence:
      size: 100Gi
      storageClass: gp3
    resources:
      requests:
        cpu: "1"
        memory: 2Gi
  extensions:
    - pgvector

redis:
  enabled: true
  architecture: replication
  replica:
    replicaCount: 2
  master:
    persistence:
      size: 10Gi

seaweedfs:
  master:
    replicas: 3
    persistence:
      size: 10Gi
  volume:
    replicas: 3
    persistence:
      size: 500Gi
  filer:
    replicas: 2
    s3:
      enabled: true

keycloak:
  replicas: 2
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
  ingress:
    enabled: true
    hostname: auth.nfyio.example.com

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/rate-limit: "100"
  tls:
    enabled: true
  hosts:
    - host: nfyio.example.com
      paths:
        - path: /
          service: gateway
    - host: storage.nfyio.example.com
      paths:
        - path: /
          service: storage

Deploy

helm install nfyio nfyio/nfyio \
  --namespace nfyio \
  --values values-production.yaml \
  --wait --timeout 10m

Watch the rollout:

kubectl -n nfyio get pods -w

Expected output once healthy:

NAME                           READY   STATUS    RESTARTS   AGE
nfyio-gateway-7b8f9d6c4-x2k1l  1/1     Running   0          3m
nfyio-gateway-7b8f9d6c4-m9j3n  1/1     Running   0          3m
nfyio-gateway-7b8f9d6c4-p4h7q  1/1     Running   0          3m
nfyio-storage-5c4d8e7f2-a1b2c  1/1     Running   0          3m
nfyio-storage-5c4d8e7f2-d3e4f  1/1     Running   0          3m
nfyio-agents-6d5e9f8g3-g5h6i   1/1     Running   0          3m
nfyio-agents-6d5e9f8g3-j7k8l   1/1     Running   0          3m
postgresql-0                    1/1     Running   0          4m
redis-master-0                  1/1     Running   0          4m
redis-replicas-0                1/1     Running   0          4m
redis-replicas-1                1/1     Running   0          3m
seaweedfs-master-0              1/1     Running   0          4m
seaweedfs-volume-0              1/1     Running   0          4m
seaweedfs-filer-0               1/1     Running   0          4m
keycloak-0                      1/1     Running   0          4m

Verify the Deployment

Health check:

curl -s https://nfyio.example.com/health | jq

{
  "status": "healthy",
  "version": "0.9.0",
  "services": {
    "database": "connected",
    "redis": "connected",
    "storage": "connected",
    "auth": "connected"
  }
}

Create your first bucket:

curl -X POST https://nfyio.example.com/api/v1/buckets \
  -H "Authorization: Bearer $YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-data", "region": "us-east-1"}'

Horizontal Pod Autoscaler

The gateway autoscaler is included in the chart. Verify it:

kubectl -n nfyio get hpa

NAME             REFERENCE                   TARGETS   MINPODS   MAXPODS   REPLICAS
nfyio-gateway    Deployment/nfyio-gateway     35%/70%   3         10        3

Upgrading

helm repo update
helm upgrade nfyio nfyio/nfyio \
  --namespace nfyio \
  --values values-production.yaml \
  --wait --timeout 10m

Check rollout status:

kubectl -n nfyio rollout status deployment/nfyio-gateway

Rollback

If something goes wrong:

# List revisions
helm -n nfyio history nfyio

# Rollback to previous
helm -n nfyio rollback nfyio 1

Key Takeaways

• Helm charts provide a single command to deploy the full nfyio stack (gateway, storage, agents, PostgreSQL, Redis, SeaweedFS, Keycloak)
• Use values-production.yaml to separate config from charts — never hardcode credentials
• HPA keeps the gateway responsive under load spikes
• SeaweedFS volume servers handle S3-compatible storage with built-in replication
• helm upgrade gives zero-downtime rolling updates; helm rollback provides instant recovery

For more details, see the installation docs and API reference.