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-installwizard - Hardened pod: non-root
www-data, no privilege escalation, every capability dropped exceptNET_BIND_SERVICE,RuntimeDefaultseccomp - 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.portchanges 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
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.
Database and Redis
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.
Exposure, probes, and storage
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.
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
- examples/production.yaml: HTTPS Ingress, existing Secrets, Redis, a 50Gi media volume, resources, and daily backups
Security
- The pod runs as
www-data(uid 33) without privilege escalation, with onlyNET_BIND_SERVICEkept (the FrankenPHP binary needs it in the bounding set to start),RuntimeDefaultseccomp, 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: setanalytics.saltoranalytics.existingSecret, andcastopod.admin.passwordorcastopod.admin.existingSecret, in those setups. - Credentials come from Secrets and accept existing Secrets. The rendered
.envis kept in a memory-backed volume, and the setup logs hide it. - Keep
castopod.admin.create=trueunless you complete/cp-installbefore 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 SyncedVerified 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)]Castopod Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Override the chart name used in resource names |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Override the full release name used in resource names |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Labels added to every resource created by this chart |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | docker.io/castopod/castopod | Castopod container image |
| image.tag | string | 1.15.5 | Castopod image tag (pinned; floating tags are rejected) |
| image.pullPolicy | string | IfNotPresent | Image pull policy Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Image pull secrets for private registries |
Castopod(12)
| Parameter | Type | Default | Description |
|---|---|---|---|
| castopod.baseURL | string | "" | Public base URL with scheme and no trailing slash. When empty, the chart |
| castopod.mediaBaseURL | string | "" | Base URL for media files; defaults to the base URL when empty |
| castopod.port | integer | 8080 | FrankenPHP listener inside the container (CADDY_HTTP_PORT, 1024-65535) |
| castopod.adminGateway | string | cp-admin | Admin area path segment |
| castopod.authGateway | string | cp-auth | Authentication area path segment |
| castopod.extraEnv | array | - | Extra environment variables for every Castopod container. CP_* variables |
| castopod.admin.create | boolean | true | Create the instance superadmin during setup when none exists. Disable |
| castopod.admin.username | string | admin | Superadmin username |
| castopod.admin.email | string | [email protected] | Superadmin email (used to log in) |
| castopod.admin.password | string | "" | Superadmin password (at least 8 characters); generated once when empty |
| castopod.admin.existingSecret | string | "" | Existing Secret with the superadmin password |
| castopod.admin.existingSecretPasswordKey | string | admin-password | Key in castopod.admin.existingSecret |
Setup(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| setup.databaseWaitTimeoutSeconds | integer | 300 | Seconds the setup init container waits for MariaDB |
| setup.resources | object | - | Resources for the setup init container |
Scheduler(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| scheduler.enabled | boolean | true | Run the Castopod task scheduler (spark tasks:run every minute) as a sidecar |
| scheduler.resources | object | - | Resources for the scheduler container |
Analytics(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| analytics.salt | string | "" | Analytics salt for hashing (generated once when empty and kept on upgrade) |
| analytics.existingSecret | string | "" | Existing secret containing the analytics salt |
| analytics.existingSecretKey | string | analytics-salt | Key in the existing secret |
Database(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.external.host | string | "" | External MariaDB host |
| database.external.port | stringinteger | 3306 | External MariaDB port |
| database.external.name | string | castopod | External database name |
| database.external.username | string | castopod | External database user |
| database.external.password | string | "" | Inline database password (stored in a chart Secret) |
| database.external.existingSecret | string | "" | Existing secret containing the database password |
| database.external.existingSecretPasswordKey | string | password | Key in the existing secret containing the password |
Persistence(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Persist /var/www/html/writable and the uploaded media in /var/www/html/public/media |
| persistence.existingClaim | string | "" | Use an existing PVC instead of creating one |
| persistence.storageClass | string | "" | Storage class for the PVC |
| persistence.accessMode | string | ReadWriteOnce | Access mode for the PVC Allowed: ReadWriteOnceReadOnlyManyReadWriteManyReadWriteOncePod |
| persistence.size | string | 10Gi | Size of the persistent volume |
| persistence.annotations | object | - | Annotations for the PVC |
Service Account(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Create a ServiceAccount |
| serviceAccount.name | string | "" | ServiceAccount name |
| serviceAccount.annotations | object | - | Annotations for the ServiceAccount |
Automount Service Account Token(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| automountServiceAccountToken | boolean | false | Mount the ServiceAccount token in the pod (Castopod does not call the Kubernetes API) |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Service type Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | HTTP service port |
| service.annotations | object | - | Annotations for the Service |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Enable ingress for Castopod |
| ingress.ingressClassName | string | traefik | Ingress class name (for example: traefik, nginx) |
| ingress.annotations | object | - | Ingress annotations |
| ingress.hosts | array | - | Ingress hosts |
| ingress.tls | array | - | Ingress TLS configuration |
Gateway API(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | false | Render Gateway API HTTPRoute resources |
| gatewayAPI.httpRoutes | array | - | HTTPRoute definitions routed to the Castopod Service by default |
Health Probes(16)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.path | string | /healthcheck | HTTP path answered by the FrankenPHP server |
| probes.startup.enabled | boolean | true | Enable the startup probe |
| probes.startup.initialDelaySeconds | integer | 5 | Startup probe initial delay |
| probes.startup.periodSeconds | integer | 5 | Startup probe period |
| probes.startup.timeoutSeconds | integer | 3 | Startup probe timeout |
| probes.startup.failureThreshold | integer | 30 | Startup probe failure threshold |
| probes.liveness.enabled | boolean | true | Enable the liveness probe |
| probes.liveness.initialDelaySeconds | integer | 0 | Liveness probe initial delay |
| probes.liveness.periodSeconds | integer | 15 | Liveness probe period |
| probes.liveness.timeoutSeconds | integer | 5 | Liveness probe timeout |
| probes.liveness.failureThreshold | integer | 3 | Liveness probe failure threshold |
| probes.readiness.enabled | boolean | true | Enable the readiness probe |
| probes.readiness.initialDelaySeconds | integer | 0 | Readiness probe initial delay |
| probes.readiness.periodSeconds | integer | 10 | Readiness probe period |
| probes.readiness.timeoutSeconds | integer | 5 | Readiness probe timeout |
| probes.readiness.failureThreshold | integer | 3 | Readiness probe failure threshold |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Resources for the Castopod container |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext | object | - | Pod security context (the image runs as www-data, uid 33) |
Container Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext | object | - | Container security context for the setup, Castopod, and scheduler containers |
Backup(20)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | false | Enable scheduled backups of the data volume (writable files and media) to S3-compatible storage |
| backup.schedule | string | 0 3 * * * | Cron schedule for backups (default: daily at 03:00 UTC) |
| backup.suspend | boolean | false | Suspend the CronJob without deleting it |
| backup.concurrencyPolicy | string | Forbid | Concurrency policy: Forbid, Replace, Allow Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | 3 | Number of successful job records to keep |
| backup.failedJobsHistoryLimit | integer | 3 | Number of failed job records to keep |
| backup.backoffLimit | integer | 1 | Maximum retries per backup job |
| backup.archivePrefix | string | castopod | Prefix for backup archive filenames |
| backup.images.archiver | string | docker.io/library/busybox:1.37 | Image used for tar/gzip backup |
| backup.images.uploader | string | docker.io/helmforge/mc:1.0.0 | Image used for S3 upload (MinIO client) |
| backup.resources | object | - | Resources for backup containers |
| backup.s3.endpoint | string | "" | S3-compatible endpoint URL |
| backup.s3.bucket | string | "" | Target bucket name |
| backup.s3.prefix | string | castopod | Key prefix within the bucket |
| backup.s3.createBucketIfNotExists | boolean | true | Auto-create the bucket if it does not exist |
| backup.s3.existingSecret | string | "" | Use an existing secret for S3 credentials |
| backup.s3.existingSecretAccessKeyKey | string | access-key | Key in the existing secret for the access key |
| backup.s3.existingSecretSecretKeyKey | string | secret-key | Key in the existing secret for the secret key |
| backup.s3.accessKey | string | "" | Inline S3 access key (ignored when existingSecret is set) |
| backup.s3.secretKey | string | "" | Inline S3 secret key (ignored when existingSecret is set) |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Node selector for the pod |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Tolerations for the pod |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Affinity rules for the pod |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Topology spread constraints for the pod |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Priority class name for the pod |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Termination grace period in seconds |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Extra labels for the pod |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Extra annotations for the pod |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Extra volumes for the pod |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Extra volume mounts for the Castopod container |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Extra manifests to deploy alongside the chart |
Mariadb(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| mariadb.enabled | boolean | true | Deploy MariaDB as a subchart |
| mariadb.architecture | string | standalone | MariaDB subchart architecture |
| mariadb.auth.database | string | castopod | Database created by the subchart |
| mariadb.auth.username | string | castopod | Database user created by the subchart |
| mariadb.auth.password | string | "" | MariaDB password (auto-generated if empty) |
Redis(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| redis.enabled | boolean | false | Deploy Redis as a subchart for the Castopod cache (authentication is required by Castopod) |
| redis.architecture | string | standalone | Redis subchart architecture |
| redis.auth.enabled | boolean | true | Redis authentication; Castopod refuses to start with Redis but no password |
| redis.auth.password | string | "" | Redis password (auto-generated by the subchart if empty) |
No schema parameters match your search
Try searching for a different keyword or reset the filter.