Skip to content
WebODM icon
v1.1.5App: v3.3.1Pinned DigestS3 Backup Ready

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

WebODM Helm Chart

WebODM provides browser-based aerial imagery processing backed by PostgreSQL with PostGIS, Redis, Celery, and a private NodeODM processor.

Features

  • Official WebODM and NodeODM images pinned by version and immutable digest.
  • Separate web, Celery worker, and authenticated processing workloads.
  • Configurable application and processing listeners independent from Services.
  • Bundled maintained PostgreSQL/PostGIS and Redis dependencies or external service contracts backed by existing Secrets.
  • Retained media and processing claims, CPU and NVIDIA GPU modes, OIDC, Ingress, Gateway API, External Secrets, PodDisruptionBudget, and scheduling controls.
  • NetworkPolicy enabled by default, restricted service-account token mounting, RuntimeDefault seccomp, probes, Helm tests, and behavioral k3d validation.

Install

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

The default installation is suitable for functional evaluation. Photogrammetry jobs need substantially more CPU, memory, and storage than the defaults.

Storage and backup

WebODM web and worker pods share the media claim. Configure ReadWriteMany storage before increasing worker.replicaCount. Back up the PostgreSQL database and the media claim at the same recovery point. NodeODM task storage is retained by default but is not a substitute for the WebODM media backup.

With the default ReadWriteOnce media claim, the worker is scheduled onto the web pod's node. A user-defined global affinity replaces this default, so keep equivalent co-location rules unless the media claim supports ReadWriteMany.

Security

The official upstream images currently initialize services as root. The chart drops all capabilities except the small set required by the upstream startup scripts, disables privilege escalation, and does not mount service account tokens. NetworkPolicy is enabled by default. Keep the NodeODM Service private, expose only the WebODM HTTP Service, and add explicit controller or external service peers when the cluster CNI enforces policy.

Architecture support

WebODM and the default CPU NodeODM image support amd64 and arm64. The bundled PostGIS image is amd64-only. Use an external PostGIS database on arm64 clusters.

GPU processing

Set processing.gpu.enabled=true to use the pinned official CUDA-enabled NodeODM image. GPU mode requests nvidia.com/gpu, supports an optional runtimeClassName, and accepts GPU-specific node selectors and tolerations. It requires amd64 nodes with a working NVIDIA device plugin and driver stack.

OpenID Connect

WebODM 3.3.0 supports one or more OIDC providers through settings_override.py. This chart renders one provider from the oidc block and reads its client secret exclusively from oidc.existingSecret. Configure the callback URI as https://YOUR_HOST/oidc/callback/ at the identity provider. Email allowlists, profile synchronization, custom scopes, and group claims are supported. See OIDC configuration.

External exposure

Ingress and Gateway API HTTPRoute are opt-in. Expose only the WebODM Service; the authenticated NodeODM Service is intentionally private. Photogrammetry uploads and downloads are large and long-running, so configure body-size and timeout settings on the selected proxy. When NetworkPolicy is enabled, add the Ingress controller or Gateway data-plane namespace to networkPolicy.ingressFrom.

External Secrets

Set externalSecrets.enabled=true and define canonical items to project the application, database, Redis, or OIDC Secrets. External Secrets Operator must already be installed. Point the corresponding existingSecret value at each projected target. See External Secrets.

Configuration reference

The complete values contract is documented inline in values.yaml and enforced by values.schema.json. Production examples are available under examples.

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

Application listener ports and Service ports are separate by design. Changing web.containerPort updates WO_PORT, the container port, and probes; changing processing.containerPort updates the NodeODM command, container port, and probes. Services continue to route by the named http target port.

Examples

Use the examples as starting points and review every resource, persistence, and network value against the target cluster. They do not contain production credentials and do not replace a restore or representative processing test.

Architecture and operations

The detailed guides separate design intent from day-two procedures:

When an external application, OIDC, database, or Redis Secret is rotated, Helm cannot checksum the data it does not own. Restart the consuming Deployments and wait for their rollouts after the secret manager updates the Kubernetes Secret.

Validation

helm lint --strict charts/webodm
helm unittest charts/webodm
helm test webodm --namespace webodm --logs

The Helm test checks both the WebODM HTTP endpoint and the authenticated NodeODM /info endpoint.

Troubleshooting

Symptom Check
Web pod waits for PostgreSQL Database host, password Secret and PostGIS initialization
Worker stays unready Redis credentials, Web Service readiness and Celery logs
Processor appears offline Registration Job and processor token consistency
Large upload fails Proxy request body and read/write timeouts
Job is evicted CPU, memory, ephemeral-storage and PVC capacity
OIDC button is absent Provider endpoints, client Secret and mounted settings override

Security Scan

Security scan results use the same Kubescape policy set as HelmForge CI.

Security Scan: webodm
Framework                  Score
MITRE + NSA + SOC2         87.9762%
Security posture acceptable.

Uninstall

PersistentVolumeClaims and the generated application Secret use the Helm keep policy. Delete them explicitly only after confirming that their data is no longer required.

References

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  User[User or API client] --> Edge[Ingress or Gateway]
  Edge --> Web[WebODM web Deployment]
  Web --> DB[(PostgreSQL and PostGIS)]
  Web --> Redis[(Redis)]
  Worker[Celery worker Deployment] --> DB
  Worker --> Redis
  Web --> Media[(Shared media PVC)]
  Worker --> Media
  Register[Registration hook Job] --> Web
  Register --> Node[Private NodeODM Deployment]
  Web --> Node
  Node --> Tasks[(Processing PVC)]
Official Contractvalues.schema.json

WebODM Values Schema Reference

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

171 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

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(4)

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

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Webodm(9)

ParameterTypeDefaultDescription
webodm.hoststring-Chart configuration parameter
webodm.debugboolean-Chart configuration parameter
webodm.existingSecretstring-Chart configuration parameter
webodm.existingSecretKeyKeystring-Chart configuration parameter
webodm.existingSecretProcessorTokenKeystring-Chart configuration parameter
webodm.secretKeystring-Chart configuration parameter
webodm.processorTokenstring-Chart configuration parameter
webodm.extraEnvarray-Chart configuration parameter
webodm.extraEnvFromarray-Chart configuration parameter

Web(9)

ParameterTypeDefaultDescription
web.containerPortinteger-Chart configuration parameter
web.concurrencyinteger-Chart configuration parameter
web.resources.requests.cpustringnumber-Chart configuration parameter
web.resources.requests.memorystring-Chart configuration parameter
web.resources.limits.cpustringnumber-Chart configuration parameter
web.resources.limits.memorystring-Chart configuration parameter
web.startupFailureThresholdinteger-Chart configuration parameter
web.startupPeriodSecondsinteger-Chart configuration parameter
web.terminationGracePeriodSecondsinteger-Chart configuration parameter

Worker(7)

ParameterTypeDefaultDescription
worker.replicaCountinteger-Chart configuration parameter
worker.concurrencyinteger-Chart configuration parameter
worker.resources.requests.cpustringnumber-Chart configuration parameter
worker.resources.requests.memorystring-Chart configuration parameter
worker.resources.limits.cpustringnumber-Chart configuration parameter
worker.resources.limits.memorystring-Chart configuration parameter
worker.terminationGracePeriodSecondsinteger-Chart configuration parameter

Processing(37)

ParameterTypeDefaultDescription
processing.enabledboolean-Chart configuration parameter
processing.containerPortinteger-Chart configuration parameter
processing.image.repositorystring-Chart configuration parameter
processing.image.tagstring-Chart configuration parameter
processing.image.digeststring-Chart configuration parameter
processing.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
processing.gpu.enabledboolean-Chart configuration parameter
processing.gpu.image.repositorystring-Chart configuration parameter
processing.gpu.image.tagstring-Chart configuration parameter
processing.gpu.image.digeststring-Chart configuration parameter
processing.gpu.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
processing.gpu.countinteger-Chart configuration parameter
processing.gpu.runtimeClassNamestring-Chart configuration parameter
processing.gpu.nodeSelectorobject-Chart configuration parameter
processing.gpu.tolerationsarray-Chart configuration parameter
processing.labelstring-Chart configuration parameter
processing.parallelQueueProcessinginteger-Chart configuration parameter
processing.maxImagesinteger-Chart configuration parameter
processing.maxConcurrencyinteger-Chart configuration parameter
processing.maxRuntimeinteger-Chart configuration parameter
processing.cleanupTasksAfterinteger-Chart configuration parameter
processing.cleanupUploadsAfterinteger-Chart configuration parameter
processing.resources.requests.cpustringnumber-Chart configuration parameter
processing.resources.requests.memorystring-Chart configuration parameter
processing.resources.requests.ephemeral-storagestring-Chart configuration parameter
processing.resources.limits.cpustringnumber-Chart configuration parameter
processing.resources.limits.memorystring-Chart configuration parameter
processing.resources.limits.ephemeral-storagestring-Chart configuration parameter
processing.terminationGracePeriodSecondsinteger-Chart configuration parameter
processing.persistence.enabledboolean-Chart configuration parameter
processing.persistence.existingClaimstring-Chart configuration parameter
processing.persistence.storageClassstring-Chart configuration parameter
processing.persistence.accessModesarray-Chart configuration parameter
processing.persistence.sizestring-Chart configuration parameter
processing.persistence.retainboolean-Chart configuration parameter
processing.persistence.annotationsobject-Chart configuration parameter
processing.tmpSizeLimitstring-Chart configuration parameter

Persistence(7)

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

Service & Networking(5)

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

Processing Service(4)

ParameterTypeDefaultDescription
processingService.portinteger-Chart configuration parameter
processingService.annotationsobject-Chart configuration parameter
processingService.ipFamilyPolicystring-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
processingService.ipFamiliesarray-Chart configuration parameter

Oidc(15)

ParameterTypeDefaultDescription
oidc.enabledboolean-Chart configuration parameter
oidc.namestring-Chart configuration parameter
oidc.clientIdstring-Chart configuration parameter
oidc.existingSecretstring-Chart configuration parameter
oidc.existingSecretClientSecretKeystring-Chart configuration parameter
oidc.authEndpointstring-Chart configuration parameter
oidc.tokenEndpointstring-Chart configuration parameter
oidc.userinfoEndpointstring-Chart configuration parameter
oidc.iconstring-Chart configuration parameter
oidc.allowedEmailsarray-Chart configuration parameter
oidc.updateProfileboolean-Chart configuration parameter
oidc.customScopesarray-Chart configuration parameter
oidc.groupClaimsarray-Chart configuration parameter
oidc.createGroupsboolean-Chart configuration parameter
oidc.ignoreGroupsarray-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

Gateway API(5)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Chart configuration parameter
gatewayAPI.parentRefsarray-Chart configuration parameter
gatewayAPI.hostnamesarray-Chart configuration parameter
gatewayAPI.annotationsobject-Chart configuration parameter
gatewayAPI.rulesarray-Chart configuration parameter

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingressFromarray-Chart configuration parameter
networkPolicy.extraEgressarray-Chart configuration parameter

Pdb(2)

ParameterTypeDefaultDescription
pdb.enabledboolean-Chart configuration parameter
pdb.minAvailableintegerstring-Chart configuration parameter

External Secrets(3)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.itemsarray-Chart configuration parameter

External Database(6)

ParameterTypeDefaultDescription
externalDatabase.hoststring-Chart configuration parameter
externalDatabase.portinteger-Chart configuration parameter
externalDatabase.databasestring-Chart configuration parameter
externalDatabase.usernamestring-Chart configuration parameter
externalDatabase.existingSecretstring-Chart configuration parameter
externalDatabase.existingSecretPasswordKeystring-Chart configuration parameter

External Redis(5)

ParameterTypeDefaultDescription
externalRedis.hoststring-Chart configuration parameter
externalRedis.portinteger-Chart configuration parameter
externalRedis.databaseinteger-Chart configuration parameter
externalRedis.existingSecretstring-Chart configuration parameter
externalRedis.existingSecretPasswordKeystring-Chart configuration parameter

Postgresql(14)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Chart configuration parameter
postgresql.image.repositorystring-Chart configuration parameter
postgresql.image.tagstring-Chart configuration parameter
postgresql.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
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.runDefaultScriptboolean-Chart configuration parameter
postgresql.initdb.scripts.10-webodm-postgis.sqlstring-Chart configuration parameter
postgresql.standalone.persistence.enabledboolean-Chart configuration parameter
postgresql.standalone.persistence.sizestring-Chart configuration parameter

Redis(8)

ParameterTypeDefaultDescription
redis.enabledboolean-Chart configuration parameter
redis.architecturestring-Chart configuration parameter
Allowed:standalonereplication
redis.auth.enabledboolean-Chart configuration parameter
redis.auth.passwordstring-Chart configuration parameter
redis.auth.existingSecretstring-Chart configuration parameter
redis.auth.existingSecretPasswordKeystring-Chart configuration parameter
redis.standalone.persistence.enabledboolean-Chart configuration parameter
redis.standalone.persistence.sizestring-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Pod Security(1)

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

Container Security(6)

ParameterTypeDefaultDescription
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.capabilities.addarray-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

Service Account(4)

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