Skip to content
Castopod icon
v1.2.15App: v1.15.5Pinned DigestS3 Backup Ready

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

Castopod Helm Chart

Deploy Castopod, the open-source podcast hosting platform with RSS feeds, a web player, analytics, and ActivityPub federation, on Kubernetes with the official castopod/castopod image.

Features

  • Ready on first start: a setup init container applies migrations and creates the superadmin from a Secret; no open /cp-install wizard
  • Hardened pod: non-root www-data, no privilege escalation, every capability dropped except NET_BIND_SERVICE, RuntimeDefault seccomp
  • Scheduler sidecar: scheduled publishing, WebSub, and federation tasks run every minute
  • MariaDB backend: HelmForge MariaDB subchart or an external server on any port
  • Optional Redis cache: authenticated HelmForge Redis subchart
  • Persistent media: uploaded audio and images survive pod restarts
  • Stable secrets: analytics salt and superadmin password survive helm upgrade
  • Configurable listener: castopod.port changes the real FrankenPHP port
  • Exposure: Ingress or Gateway API HTTPRoutes
  • S3 backups: scheduled archives of the data volume

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install castopod helmforge/castopod \
  --set castopod.baseURL=https://podcast.example.com

OCI registry:

helm install castopod oci://ghcr.io/helmforgedev/helm/castopod \
  --set castopod.baseURL=https://podcast.example.com

castopod.baseURL only sets the URL Castopod embeds in links and feeds; it does not expose the Service. Enable ingress or gatewayAPI for that hostname before using the public URL.

Quick Start

Without a base URL, Ingress, or HTTPRoute, the chart uses http://localhost:8080 and disables HTTPS redirection, which suits a local check:

helm install castopod helmforge/castopod
kubectl rollout status deploy/castopod-castopod --timeout=300s
kubectl get secret castopod-castopod-admin -o jsonpath='{.data.admin-password}' | base64 -d; echo
kubectl port-forward svc/castopod-castopod 8080:80

Open http://localhost:8080/cp-auth/login and log in with [email protected] and the password above. Resource names follow <release>-castopod.

Architecture

The pod runs a setup init container, the castopod container (FrankenPHP), and a scheduler sidecar (supercronic), all from the same image. The setup container waits for MariaDB, runs the upstream bootstrap (.env, migrations, cache), and creates the superadmin once. See DESIGN.md for the design, including why the upstream s6-overlay supervisor is not used.

Configuration

Application

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

Database and Redis

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

Exposure, probes, and storage

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

Every key is documented in values.yaml and validated by values.schema.json. See docs/configuration.md for external databases, Redis, SMTP, and backups.

Examples

Security

  • The pod runs as www-data (uid 33) without privilege escalation, with only NET_BIND_SERVICE kept (the FrankenPHP binary needs it in the bounding set to start), RuntimeDefault seccomp, and no ServiceAccount token.
  • The root filesystem stays writable because Caddy and the bootstrap write to the image tree.
  • The generated analytics salt and superadmin password are read back from their Secrets with lookup. Renderers without cluster access, such as client-side GitOps rendering, generate new values on every render: set analytics.salt or analytics.existingSecret, and castopod.admin.password or castopod.admin.existingSecret, in those setups.
  • Credentials come from Secrets and accept existing Secrets. The rendered .env is kept in a memory-backed volume, and the setup logs hide it.
  • Keep castopod.admin.create=true unless you complete /cp-install before exposing the instance; the first visitor of the wizard becomes the owner.

Troubleshooting

Symptom Check
Pod stuck in Init:0/1 kubectl logs deploy/<release>-castopod -c setup; MariaDB is unreachable or the credentials are wrong
Redirect loop or HTTPS errors behind a proxy Set castopod.baseURL to the public https:// URL and forward X-Forwarded-Proto
Login rejected Log in with the email, not the username; read the password from <release>-castopod-admin
Scheduled episodes never publish Confirm scheduler.enabled=true and read -c scheduler logs

More Information

Security Scan: castopod

Framework Score
MITRE + NSA + SOC2 87.878784%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  user[Listeners and admins] --> edge[Ingress or HTTPRoute]
  edge --> svc[Service http]
  svc --> app[castopod container<br/>FrankenPHP]
  subgraph pod[Castopod pod]
    setup[setup init container] --> app
    app --- sched[scheduler sidecar<br/>supercronic]
  end
  setup --> db[(MariaDB)]
  app --> db
  app -.optional.-> redis[(Redis)]
  app --> pvc[(Data PVC<br/>writable + public-media)]
  backup[backup CronJob] --> pvc
  backup --> s3[(S3 bucket)]
Official Contractvalues.schema.json

Castopod Values Schema Reference

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

113 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/castopod/castopodCastopod container image
image.tagstring1.15.5Castopod image tag (pinned; floating tags are rejected)
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Castopod(12)

ParameterTypeDefaultDescription
castopod.baseURLstring""Public base URL with scheme and no trailing slash. When empty, the chart
castopod.mediaBaseURLstring""Base URL for media files; defaults to the base URL when empty
castopod.portinteger8080FrankenPHP listener inside the container (CADDY_HTTP_PORT, 1024-65535)
castopod.adminGatewaystringcp-adminAdmin area path segment
castopod.authGatewaystringcp-authAuthentication area path segment
castopod.extraEnvarray-Extra environment variables for every Castopod container. CP_* variables
castopod.admin.createbooleantrueCreate the instance superadmin during setup when none exists. Disable
castopod.admin.usernamestringadminSuperadmin username
castopod.admin.emailstring[email protected]Superadmin email (used to log in)
castopod.admin.passwordstring""Superadmin password (at least 8 characters); generated once when empty
castopod.admin.existingSecretstring""Existing Secret with the superadmin password
castopod.admin.existingSecretPasswordKeystringadmin-passwordKey in castopod.admin.existingSecret

Setup(2)

ParameterTypeDefaultDescription
setup.databaseWaitTimeoutSecondsinteger300Seconds the setup init container waits for MariaDB
setup.resourcesobject-Resources for the setup init container

Scheduler(2)

ParameterTypeDefaultDescription
scheduler.enabledbooleantrueRun the Castopod task scheduler (spark tasks:run every minute) as a sidecar
scheduler.resourcesobject-Resources for the scheduler container

Analytics(3)

ParameterTypeDefaultDescription
analytics.saltstring""Analytics salt for hashing (generated once when empty and kept on upgrade)
analytics.existingSecretstring""Existing secret containing the analytics salt
analytics.existingSecretKeystringanalytics-saltKey in the existing secret

Database(7)

ParameterTypeDefaultDescription
database.external.hoststring""External MariaDB host
database.external.portstringinteger3306External MariaDB port
database.external.namestringcastopodExternal database name
database.external.usernamestringcastopodExternal database user
database.external.passwordstring""Inline database password (stored in a chart Secret)
database.external.existingSecretstring""Existing secret containing the database password
database.external.existingSecretPasswordKeystringpasswordKey in the existing secret containing the password

Persistence(6)

ParameterTypeDefaultDescription
persistence.enabledbooleantruePersist /var/www/html/writable and the uploaded media in /var/www/html/public/media
persistence.existingClaimstring""Use an existing PVC instead of creating one
persistence.storageClassstring""Storage class for the PVC
persistence.accessModestringReadWriteOnceAccess mode for the PVC
Allowed:ReadWriteOnceReadOnlyManyReadWriteManyReadWriteOncePod
persistence.sizestring10GiSize of the persistent volume
persistence.annotationsobject-Annotations for the PVC

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a ServiceAccount
serviceAccount.namestring""ServiceAccount name
serviceAccount.annotationsobject-Annotations for the ServiceAccount

Automount Service Account Token(1)

ParameterTypeDefaultDescription
automountServiceAccountTokenbooleanfalseMount the ServiceAccount token in the pod (Castopod does not call the Kubernetes API)

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestringClusterIPService type
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80HTTP service port
service.annotationsobject-Annotations for the Service

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseEnable ingress for Castopod
ingress.ingressClassNamestringtraefikIngress class name (for example: traefik, nginx)
ingress.annotationsobject-Ingress annotations
ingress.hostsarray-Ingress hosts
ingress.tlsarray-Ingress TLS configuration

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledbooleanfalseRender Gateway API HTTPRoute resources
gatewayAPI.httpRoutesarray-HTTPRoute definitions routed to the Castopod Service by default

Health Probes(16)

ParameterTypeDefaultDescription
probes.pathstring/healthcheckHTTP path answered by the FrankenPHP server
probes.startup.enabledbooleantrueEnable the startup probe
probes.startup.initialDelaySecondsinteger5Startup probe initial delay
probes.startup.periodSecondsinteger5Startup probe period
probes.startup.timeoutSecondsinteger3Startup probe timeout
probes.startup.failureThresholdinteger30Startup probe failure threshold
probes.liveness.enabledbooleantrueEnable the liveness probe
probes.liveness.initialDelaySecondsinteger0Liveness probe initial delay
probes.liveness.periodSecondsinteger15Liveness probe period
probes.liveness.timeoutSecondsinteger5Liveness probe timeout
probes.liveness.failureThresholdinteger3Liveness probe failure threshold
probes.readiness.enabledbooleantrueEnable the readiness probe
probes.readiness.initialDelaySecondsinteger0Readiness probe initial delay
probes.readiness.periodSecondsinteger10Readiness probe period
probes.readiness.timeoutSecondsinteger5Readiness probe timeout
probes.readiness.failureThresholdinteger3Readiness probe failure threshold

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Resources for the Castopod container

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContextobject-Pod security context (the image runs as www-data, uid 33)

Container Security(1)

ParameterTypeDefaultDescription
securityContextobject-Container security context for the setup, Castopod, and scheduler containers

Backup(20)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable scheduled backups of the data volume (writable files and media) to S3-compatible storage
backup.schedulestring0 3 * * *Cron schedule for backups (default: daily at 03:00 UTC)
backup.suspendbooleanfalseSuspend the CronJob without deleting it
backup.concurrencyPolicystringForbidConcurrency policy: Forbid, Replace, Allow
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger3Number of successful job records to keep
backup.failedJobsHistoryLimitinteger3Number of failed job records to keep
backup.backoffLimitinteger1Maximum retries per backup job
backup.archivePrefixstringcastopodPrefix for backup archive filenames
backup.images.archiverstringdocker.io/library/busybox:1.37Image used for tar/gzip backup
backup.images.uploaderstringdocker.io/helmforge/mc:1.0.0Image used for S3 upload (MinIO client)
backup.resourcesobject-Resources for backup containers
backup.s3.endpointstring""S3-compatible endpoint URL
backup.s3.bucketstring""Target bucket name
backup.s3.prefixstringcastopodKey prefix within the bucket
backup.s3.createBucketIfNotExistsbooleantrueAuto-create the bucket if it does not exist
backup.s3.existingSecretstring""Use an existing secret for S3 credentials
backup.s3.existingSecretAccessKeyKeystringaccess-keyKey in the existing secret for the access key
backup.s3.existingSecretSecretKeyKeystringsecret-keyKey in the existing secret for the secret key
backup.s3.accessKeystring""Inline S3 access key (ignored when existingSecret is set)
backup.s3.secretKeystring""Inline S3 secret key (ignored when existingSecret is set)

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for the pod

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for the pod

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for the pod

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints for the pod

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name for the pod

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Termination grace period in seconds

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Extra labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Extra annotations for the pod

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Extra volumes for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Extra volume mounts for the Castopod container

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra manifests to deploy alongside the chart

Mariadb(5)

ParameterTypeDefaultDescription
mariadb.enabledbooleantrueDeploy MariaDB as a subchart
mariadb.architecturestringstandaloneMariaDB subchart architecture
mariadb.auth.databasestringcastopodDatabase created by the subchart
mariadb.auth.usernamestringcastopodDatabase user created by the subchart
mariadb.auth.passwordstring""MariaDB password (auto-generated if empty)

Redis(4)

ParameterTypeDefaultDescription
redis.enabledbooleanfalseDeploy Redis as a subchart for the Castopod cache (authentication is required by Castopod)
redis.architecturestringstandaloneRedis subchart architecture
redis.auth.enabledbooleantrueRedis authentication; Castopod refuses to start with Redis but no password
redis.auth.passwordstring""Redis password (auto-generated by the subchart if empty)