Skip to content
Middleware icon
v1.2.14App: v0.3.1Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Middleware Helm Chart

Deploy Middleware, the open-source DORA metrics platform, with the official middlewareeng/middleware image and a separate PostgreSQL database. The chart preserves the application's encryption keys, runs database migrations before startup, and validates the complete frontend, analytics, sync, and embedded Redis process set before a pod becomes ready.

Features

  • Measures deployment frequency, lead time for changes, change failure rate, and time to restore.
  • Uses the HelmForge PostgreSQL subchart or an operator-managed PostgreSQL.
  • Runs the upstream-supported embedded Redis process on loopback.
  • Persists encryption keys at the path used by Middleware 0.3.1.
  • Applies database migrations in an init container before the application.
  • Supports configurable application and Service ports, Ingress, scheduling, additional volumes, and extra manifests.
  • Creates a tokenless ServiceAccount, RuntimeDefault seccomp profile, capability drop, and NetworkPolicy by default.
  • Rejects ambiguous datastore modes and unsupported remote Redis settings.

Installation

Using the HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install middleware helmforge/middleware --namespace middleware --create-namespace

Using OCI:

helm install middleware oci://ghcr.io/helmforgedev/helm/middleware \
  --namespace middleware \
  --create-namespace

The default installation creates one Middleware Deployment, a PVC for the application encryption keys, and a standalone PostgreSQL release. Redis runs inside the official application container because the upstream 0.3.1 remote Redis client does not support password authentication and unconditionally uses TLS for non-loopback hosts.

Architecture

Middleware packages three processes in one container:

Process Default port Purpose
Frontend 3333 Next.js user interface
Analytics API 9696 DORA data and API operations
Sync server 9697 Provider ingestion and synchronization

The Service exposes only the frontend through the named http port. Startup and readiness probes require all three application listeners plus the loopback Redis listener. Changing middleware.frontendPort, middleware.analyticsPort, or middleware.syncPort changes both the Kubernetes ports and the upstream process environment.

Before the application starts, an init container runs the migrations shipped in the same official image. It uses dbmate --wait, then writes the signal the upstream analytics process expects in a shared emptyDir. This is required because disabling the image's embedded PostgreSQL also disables its original initializer.

Configuration

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

The complete contract is documented in configuration.md and enforced by values.schema.json plus template validation.

Examples

Bundled PostgreSQL

The defaults are sufficient. For a durable production password, create a Secret and let the subchart consume it:

read -r -s -p 'PostgreSQL superuser password: ' MIDDLEWARE_POSTGRES_PASSWORD
printf '\n'
read -r -s -p 'PostgreSQL application password: ' MIDDLEWARE_DB_PASSWORD
printf '\n'
kubectl create namespace middleware --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret generic middleware-postgresql-credentials \
  --namespace middleware \
  --from-literal=postgres-password="$MIDDLEWARE_POSTGRES_PASSWORD" \
  --from-literal=user-password="$MIDDLEWARE_DB_PASSWORD"
unset MIDDLEWARE_POSTGRES_PASSWORD MIDDLEWARE_DB_PASSWORD
postgresql:
  enabled: true
  auth:
    database: mhq-oss
    username: middleware
    existingSecret: middleware-postgresql-credentials
    existingSecretUserPasswordKey: user-password

persistence:
  enabled: true
  size: 1Gi

Replication mode additionally requires the configured replication password key.

External PostgreSQL

postgresql:
  enabled: false

externalDatabase:
  enabled: true
  host: postgres.database.svc.cluster.local
  port: 5432
  name: mhq-oss
  user: middleware
  existingSecret: middleware-database
  existingSecretPasswordKey: password
  sslMode: require

Create middleware-database before installation, or source it through an external secret controller. The chart also accepts an inline externalDatabase.password for development and places it in a chart-managed Secret; do not commit that value to source control.

Custom application and Service ports

middleware:
  frontendPort: 4333
  analyticsPort: 10696
  syncPort: 10697

service:
  port: 8080

The Service continues to target the named frontend port, so service.port does not need to match middleware.frontendPort.

Security

The default pod does not receive a Kubernetes API token. The pod uses the RuntimeDefault seccomp profile, while both the migration and application containers disallow privilege escalation and drop all Linux capabilities. The upstream image starts as root and expands packaged runtime artifacts on first startup, so this chart cannot safely set runAsNonRoot or a read-only root filesystem without a rebuilt upstream image.

The default NetworkPolicy permits inbound traffic only to the named frontend port. Egress remains unrestricted because Middleware connects to operator- selected Git, issue tracker, and CI providers. Restrict egress at the platform layer only after enumerating all required destinations.

Database passwords are referenced from Kubernetes Secrets. Inline external passwords are moved into a Secret and are never placed directly in the Deployment environment. Prefer externalDatabase.existingSecret in GitOps environments.

See security.md for the threat boundaries and residual upstream constraints.

Operations

Back up both PostgreSQL and the key PVC. PostgreSQL contains DORA records and integration metadata; the persisted config.ini contains the RSA key pair used to encrypt stored integration credentials. Restoring only one of these data sets can make provider credentials unusable.

The application Deployment uses Recreate and a single replica. The key PVC defaults to ReadWriteOnce, and upstream does not define a multi-replica coordination model. Scale and protect PostgreSQL independently, but keep the application tier at one replica.

Detailed backup, restore, rollout, and diagnostic commands are in operations.md.

Troubleshooting

Inspect migration and application logs separately:

kubectl logs -n middleware deployment/middleware-middleware -c migrate-database
kubectl logs -n middleware deployment/middleware-middleware -c middleware --tail=200
kubectl describe pod -n middleware -l app.kubernetes.io/instance=middleware

If the init container waits for PostgreSQL, verify the resolved Service name, Secret key, network path, and externalDatabase.sslMode. If the frontend is open but the pod is not Ready, inspect the analytics and sync listener logs; the readiness probe intentionally checks all three processes.

If integrations cannot be decrypted after a restore, confirm that the PVC was restored from the same recovery point as PostgreSQL and contains mhq/config/config.ini at the mounted application path.

Upgrade notes

  • Preserve the existing key PVC across upgrades.
  • Restore or reuse PostgreSQL credential Secrets when PostgreSQL PVCs already contain data; generating a new password will not change the database user.
  • Remote or subchart Redis values are rejected because Middleware 0.3.1 cannot consume them safely. Remove legacy redis.enabled: true and externalRedis.enabled: true overrides.
  • Verify all three listeners after an image change because they are supervised independently inside the container.

Documentation

Security Scan: middleware

Framework Score
MITRE + NSA + SOC2 79.29292%

The score is refreshed by CI from rendered manifests. It does not replace application-image vulnerability scanning or a review of external provider credentials.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  client[Browser]
  service[Middleware Service]

  subgraph pod[Middleware Deployment]
    migration[dbmate migration init container]
    frontend[Next.js frontend]
    analytics[Analytics API]
    sync[Sync server]
    redis[Embedded Redis]
    signal[Shared db_init signal]
    keys[Encryption-key PVC]
  end

  subgraph database[Database boundary]
    bundled[Bundled PostgreSQL StatefulSet]
    external[External PostgreSQL]
  end

  client --> service --> frontend
  migration --> bundled
  migration -. external mode .-> external
  migration --> signal --> analytics
  frontend --> analytics
  frontend --> sync
  analytics --> redis
  analytics --> keys
  analytics --> bundled
  analytics -. external mode .-> external
Official Contractvalues.schema.json

Middleware Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

77 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Chart configuration parameter

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Middleware(8)

ParameterTypeDefaultDescription
middleware.frontendPortinteger-Chart configuration parameter
middleware.analyticsPortinteger-Chart configuration parameter
middleware.syncPortinteger-Chart configuration parameter
middleware.environmentstring-Chart configuration parameter
middleware.internalDbEnabledstringfalseChart configuration parameter
middleware.internalRedisEnabledstringtrueChart configuration parameter
middleware.timezonestring-Chart configuration parameter
middleware.extraEnvarray-Chart configuration parameter

External Database(9)

ParameterTypeDefaultDescription
externalDatabase.enabledboolean-Chart configuration parameter
externalDatabase.hoststring-Chart configuration parameter
externalDatabase.portinteger-Chart configuration parameter
externalDatabase.namestring-Chart configuration parameter
externalDatabase.userstring-Chart configuration parameter
externalDatabase.passwordstring-Chart configuration parameter
externalDatabase.existingSecretstring-Chart configuration parameter
externalDatabase.existingSecretPasswordKeystring-Chart configuration parameter
externalDatabase.sslModestring-Chart configuration parameter
Allowed:disablerequireverify-caverify-full

External Redis(3)

ParameterTypeDefaultDescription
externalRedis.enabledboolean-Chart configuration parameter
externalRedis.hoststring-Chart configuration parameter
externalRedis.portinteger-Chart configuration parameter

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledboolean-Chart configuration parameter
persistence.sizestring-Chart configuration parameter
persistence.storageClassstring-Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Health Probes(3)

ParameterTypeDefaultDescription
probes.startupany-Chart configuration parameter
probes.livenessany-Chart configuration parameter
probes.readinessany-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Chart configuration parameter

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined

Container Security(2)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.additionalIngressFromarray-Chart configuration parameter
networkPolicy.additionalEgressarray-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Postgresql(10)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Chart configuration parameter
postgresql.nameOverridestring-Chart configuration parameter
postgresql.fullnameOverridestring-Chart configuration parameter
postgresql.architecturestring-Chart configuration parameter
Allowed:standalonereplication
postgresql.auth.databasestring-Chart configuration parameter
postgresql.auth.usernamestring-Chart configuration parameter
postgresql.auth.passwordstring-Chart configuration parameter
postgresql.auth.existingSecretstring-Chart configuration parameter
postgresql.auth.existingSecretUserPasswordKeystring-Chart configuration parameter
postgresql.initdb.scripts.02-middleware-database-owner.shstring-Chart configuration parameter

Redis(1)

ParameterTypeDefaultDescription
redis.enabledboolean-Chart configuration parameter