Skip to main content

Helm Chart Deployment

Deploy ArgusAI using Helm for template-based, customizable Kubernetes deployments.

Why Helm?
  • Customizable: Override any configuration via values.yaml
  • Upgradable: Easy upgrades with helm upgrade
  • Reproducible: Consistent deployments across environments
  • Maintainable: Single source of truth for configuration

Prerequisites​

  • Kubernetes cluster 1.25+
  • Helm 3.10+
  • kubectl configured with cluster access

Quick Start​

# Clone the repository
git clone https://github.com/project-argusai/ArgusAI.git
cd ArgusAI

# Create namespace
kubectl create namespace argusai

# Install with required secrets
helm install argusai ./charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
  --set secrets.jwtSecretKey=$(openssl rand -hex 32)

Chart Information​

PropertyValue
Chart Nameargusai
Chart Version0.1.0
App Version1.0.0
Sourcecharts/argusai/

Installation Options​

Basic Installation​

helm install argusai ./charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey="your-fernet-key" \
  --set secrets.jwtSecretKey="your-jwt-secret"

Installation with Custom Values File​

Create a my-values.yaml:

# Custom values for production
backend:
  replicaCount: 2
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "2Gi"
      cpu: "2000m"

frontend:
  replicaCount: 2

config:
  debug: false
  logLevel: "WARNING"

secrets:
  encryptionKey: "your-fernet-key"
  jwtSecretKey: "your-jwt-secret"
  openaiApiKey: "sk-..."

persistence:
  size: 50Gi
  storageClass: "fast-ssd"

ingress:
  enabled: true
  hosts:
    - host: argusai.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: argusai-tls
      hosts:
        - argusai.example.com

Install with the custom values:

helm install argusai ./charts/argusai \
  --namespace argusai \
  -f my-values.yaml

From OCI Registry (Future)​

# Coming soon - pull from GitHub Container Registry
helm install argusai oci://ghcr.io/project-argusai/charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey="..." \
  --set secrets.jwtSecretKey="..."

Configuration Reference​

Global Settings​

ParameterDescriptionDefault
nameOverrideOverride chart name""
fullnameOverrideOverride full release name""
imagePullSecretsDocker registry secrets[]

Backend Configuration​

ParameterDescriptionDefault
backend.replicaCountNumber of backend replicas1
backend.image.repositoryBackend image repositoryghcr.io/project-argusai/argusai-backend
backend.image.tagBackend image taglatest
backend.image.pullPolicyImage pull policyIfNotPresent
backend.resources.requests.memoryMemory request512Mi
backend.resources.requests.cpuCPU request250m
backend.resources.limits.memoryMemory limit1Gi
backend.resources.limits.cpuCPU limit1000m
backend.service.typeService typeClusterIP
backend.service.portService port8000

Frontend Configuration​

ParameterDescriptionDefault
frontend.replicaCountNumber of frontend replicas1
frontend.image.repositoryFrontend image repositoryghcr.io/project-argusai/argusai-frontend
frontend.image.tagFrontend image taglatest
frontend.image.pullPolicyImage pull policyIfNotPresent
frontend.resources.requests.memoryMemory request256Mi
frontend.resources.requests.cpuCPU request100m
frontend.resources.limits.memoryMemory limit512Mi
frontend.resources.limits.cpuCPU limit500m
frontend.service.typeService typeClusterIP
frontend.service.portService port3000

Application Configuration​

ParameterDescriptionDefault
config.debugEnable debug modefalse
config.logLevelLog levelINFO
config.corsOriginsCORS allowed originshttp://localhost:3000
config.databaseUrlDatabase connection stringsqlite:///data/app.db
config.sslEnabledEnable SSLfalse
config.maxCamerasMaximum cameras10
config.eventRetentionDaysEvent retention days30

Secrets​

Required Secrets

encryptionKey and jwtSecretKey are required for the application to start.

ParameterDescriptionRequired
secrets.encryptionKeyFernet encryption keyYes
secrets.jwtSecretKeyJWT signing secretYes
secrets.openaiApiKeyOpenAI API keyNo
secrets.xaiApiKeyxAI Grok API keyNo
secrets.anthropicApiKeyAnthropic Claude API keyNo
secrets.googleAiApiKeyGoogle AI API keyNo
secrets.vapidPrivateKeyVAPID private key (push notifications)No
secrets.vapidPublicKeyVAPID public key (push notifications)No
secrets.mqttPasswordMQTT password (Home Assistant)No

Generate Required Keys​

# Generate Fernet encryption key
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Generate JWT secret key
openssl rand -hex 32

# Generate VAPID keys (for push notifications)
npx web-push generate-vapid-keys

Persistence​

ParameterDescriptionDefault
persistence.enabledEnable persistent storagetrue
persistence.storageClassStorage class name"" (default)
persistence.accessModeAccess modeReadWriteOnce
persistence.sizeStorage size10Gi
persistence.annotationsPVC annotations{}

Ingress​

ParameterDescriptionDefault
ingress.enabledEnable ingressfalse
ingress.classNameIngress class namenginx
ingress.annotationsIngress annotations{}
ingress.hostsIngress hosts configurationSee below
ingress.tlsTLS configuration[]

Default host configuration:

ingress:
  hosts:
    - host: argusai.local
      paths:
        - path: /
          pathType: Prefix

Security​

ParameterDescriptionDefault
podSecurityContext.runAsNonRootRun as non-roottrue
podSecurityContext.runAsUserRun as user ID1000
podSecurityContext.fsGroupFilesystem group1000
securityContext.allowPrivilegeEscalationAllow privilege escalationfalse

Scheduling​

ParameterDescriptionDefault
nodeSelectorNode selector labels{}
tolerationsPod tolerations[]
affinityPod affinity rules{}

Service Account​

ParameterDescriptionDefault
serviceAccount.createCreate service accounttrue
serviceAccount.annotationsService account annotations{}
serviceAccount.nameService account name"" (auto-generated)

Common Operations​

Upgrade​

# Upgrade to new values
helm upgrade argusai ./charts/argusai \
  --namespace argusai \
  -f my-values.yaml

# Upgrade to new chart version
helm upgrade argusai ./charts/argusai \
  --namespace argusai \
  --reuse-values

Rollback​

# View history
helm history argusai -n argusai

# Rollback to previous release
helm rollback argusai -n argusai

# Rollback to specific revision
helm rollback argusai 2 -n argusai

Uninstall​

# Uninstall (keeps PVC by default)
helm uninstall argusai -n argusai

# Delete PVC manually if needed
kubectl delete pvc argusai-data -n argusai

Validate Chart​

# Lint the chart
helm lint ./charts/argusai

# Template without installing
helm template argusai ./charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey="test" \
  --set secrets.jwtSecretKey="test"

# Dry run installation
helm install argusai ./charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey="test" \
  --set secrets.jwtSecretKey="test" \
  --dry-run

Advanced Configuration​

Using External Secrets​

For production, use external secret management instead of Helm values:

With External Secrets Operator​

# external-secret.yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: argusai-secrets
  namespace: argusai
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: argusai-secrets
  data:
    - secretKey: ENCRYPTION_KEY
      remoteRef:
        key: argusai/encryption-key
    - secretKey: JWT_SECRET_KEY
      remoteRef:
        key: argusai/jwt-secret

Then install without secrets in values:

helm install argusai ./charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey="" \
  --set secrets.jwtSecretKey=""

Using PostgreSQL​

Deploy PostgreSQL and configure ArgusAI to use it:

# Install PostgreSQL
helm install postgres bitnami/postgresql \
  --namespace argusai \
  --set auth.database=argusai \
  --set auth.username=argusai \
  --set auth.password=secure-password

# Install ArgusAI with PostgreSQL
helm install argusai ./charts/argusai \
  --namespace argusai \
  --set config.databaseUrl="postgresql://argusai:secure-password@postgres-postgresql:5432/argusai" \
  --set secrets.encryptionKey="..." \
  --set secrets.jwtSecretKey="..."

High Availability Setup​

# ha-values.yaml
backend:
  replicaCount: 3
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "2Gi"
      cpu: "2000m"

frontend:
  replicaCount: 3

config:
  databaseUrl: "postgresql://argusai:password@postgres:5432/argusai"

persistence:
  storageClass: "replicated-storage"

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: app.kubernetes.io/name
              operator: In
              values:
                - argusai
        topologyKey: kubernetes.io/hostname

Multi-Environment Setup​

# Development
helm install argusai-dev ./charts/argusai \
  -n argusai-dev \
  -f values-dev.yaml

# Staging
helm install argusai-staging ./charts/argusai \
  -n argusai-staging \
  -f values-staging.yaml

# Production
helm install argusai-prod ./charts/argusai \
  -n argusai-prod \
  -f values-prod.yaml

Post-Installation Notes​

After installation, Helm displays helpful notes:

ArgusAI has been deployed!

1. Get the application URL:
   kubectl --namespace argusai port-forward service/argusai-frontend 3000:3000
   Then open http://localhost:3000

2. Get backend API URL (for debugging):
   kubectl --namespace argusai port-forward service/argusai-backend 8000:8000
   Then open http://localhost:8000/docs

3. Check deployment status:
   kubectl --namespace argusai get pods -l app.kubernetes.io/instance=argusai

4. View logs:
   kubectl --namespace argusai logs -l app.kubernetes.io/component=backend -f
   kubectl --namespace argusai logs -l app.kubernetes.io/component=frontend -f

Troubleshooting​

Chart Installation Fails​

# Check helm status
helm status argusai -n argusai

# View helm notes
helm get notes argusai -n argusai

# View rendered manifests
helm get manifest argusai -n argusai

Missing Secrets Warning​

If you see warnings about missing secrets:

# Verify secrets are set
helm get values argusai -n argusai | grep -E "(encryption|jwt)"

# Update with secrets
helm upgrade argusai ./charts/argusai \
  --namespace argusai \
  --set secrets.encryptionKey="your-key" \
  --set secrets.jwtSecretKey="your-secret"

Pod Scheduling Issues​

# Check pod events
kubectl describe pod -l app.kubernetes.io/instance=argusai -n argusai

# Check node resources
kubectl top nodes

# Check for taints
kubectl describe nodes | grep -A5 Taints

Next Steps​