Castopod on Google Cloud Run

Castopod is an open-source, ActivityPub-native podcast hosting platform built on CodeIgniter 4 (PHP 8) and served by FrankenPHP/Caddy. This module deploys Castopod on Cloud Run v2 on top of the App_CloudRun foundation, which provisions and manages the shared Google Cloud infrastructure.

This guide focuses on the cloud services Castopod uses and how to explore and operate them from the Google Cloud Console and the command line. For the mechanics common to every Cloud Run application — service identity, ingress and load balancing, scaling and concurrency, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, backups, and the deployment lifecycle — refer to the App_CloudRun foundation guide rather than repeating them here.

1. Overview

Castopod runs as a PHP/FrankenPHP container on Cloud Run v2, listening on port 8080. The deployment wires together a focused set of Google Cloud services:

Capability	Google Cloud service	Notes
Compute	Cloud Run v2	FrankenPHP/Caddy service, 1 vCPU / 2 GiB by default, serverless autoscaling; scale-to-zero supported
Database	Cloud SQL for MySQL 8.0	Required — Castopod does not support PostgreSQL or other engines
Media storage	Cloud Storage + Cloud Filestore (NFS)	A `media` bucket is provisioned; NFS is enabled by default to persist uploads across restarts
Cache	Redis (optional)	File cache (`CP_CACHE_HANDLER = file`) is the default; Redis is opt-in
Secrets	Secret Manager	Auto-generated `CP_ANALYTICS_SALT`; database password
Ingress	Cloud Run URL / Cloud Load Balancing	Default `run.app` URL; optional external HTTPS load balancer + custom domain

Sensible defaults worth knowing up front:

MySQL 8.0 is mandatory. The database engine is fixed (database_type = "MYSQL_8_0") by the module; selecting PostgreSQL or any other engine breaks startup.
The database config is written into Castopod's .env, not env vars. Castopod (CodeIgniter 4) reads dot-notated keys (database.default.hostname …) that cannot be Cloud Run env var names. The container entrypoint materialises them into .env from the injected DB_* variables, and resolves a TCP host (DB_IP) because CI4's mysqli driver cannot use the Cloud SQL socket directory.
CP_ANALYTICS_SALT is generated automatically and stored in Secret Manager. Keep it stable — it anonymises listener analytics, and changing it breaks de-duplication continuity for previously recorded listeners.
Scale-to-zero is enabled by default (min_instance_count = 0). Cold starts add a few seconds of latency to the first request after idle. Set min_instance_count = 1 to keep Castopod always warm.
max_instance_count = 1 by default. Do not scale beyond one instance unless the shared media filesystem (NFS/GCS) and a shared cache are confirmed multi-instance-safe.
NFS is enabled by default (enable_nfs = true) to persist uploaded media across container restarts. Castopod stores episode audio and artwork on the filesystem, not in the database.
The base URL is derived automatically. The entrypoint sets CP_BASEURL from the runtime CLOUDRUN_SERVICE_URL, so podcast feed and media URLs reflect the real service address.
CodeIgniter migrations run on container start — there is no separate migrate job; the schema is created on first boot after the db-init job provisions the DB and user.

2. Google Cloud Services & How to Explore Them

All commands assume PROJECT and REGION are set. Service and resource names are reported in the deployment Outputs.

A. Cloud Run — the Castopod service

Castopod runs as a Cloud Run v2 service that autoscales by request load between the minimum and maximum instance counts. Each deployment creates an immutable revision; traffic can be split across revisions for safe rollouts.

Console: Cloud Run → select the service for revisions, traffic, logs, and metrics.

CLI:

gcloud run services list --project "$PROJECT" --region "$REGION" \
  --filter="metadata.name~castopod"
gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

See App_CloudRun for scaling, concurrency, execution environment, and traffic splitting.

B. Cloud SQL for MySQL 8.0

Castopod stores all application data (podcasts, episodes, users, analytics) in a managed Cloud SQL for MySQL 8.0 instance. The service connects privately — the entrypoint dials the Cloud SQL private IP over TCP (CodeIgniter's mysqli driver cannot use the Auth Proxy socket directory); no public IP is exposed. On first deploy an initialization Job creates the application database and user.

Console: SQL → select the instance for connections, backups, flags, metrics.

CLI:

gcloud sql instances list --project "$PROJECT" --filter="name~castopod"
gcloud sql instances describe <instance-name> --project "$PROJECT"
gcloud sql connect <instance-name> --user=<db-user> --database=<db-name> --project "$PROJECT"

The instance name, database, user, and password secret are in the Outputs. See App_CloudRun for the connection model, backups, and password rotation.

C. Cloud Storage & media persistence

A dedicated Cloud Storage media bucket is provisioned automatically. Because Castopod writes uploaded audio and artwork to the container filesystem under /var/www/castopod/public/media, Cloud Filestore (NFS) is enabled by default (enable_nfs = true, mounted at nfs_mount_path) so those files survive restarts.

Console: Cloud Storage → Buckets; Filestore → Instances.

CLI:

gcloud storage buckets list --project "$PROJECT" --filter="name~media"
gcloud filestore instances list --project "$PROJECT"

See App_CloudRun for GCS Fuse, NFS, and CMEK options.

D. Redis (object cache)

Redis is disabled by default — Castopod uses a filesystem cache (CP_CACHE_HANDLER = file). When enable_redis = true, the module injects REDIS_HOST and REDIS_PORT for Castopod's object cache. When redis_host is left empty and enable_nfs is true, the NFS server VM's IP is used as the Redis endpoint.

Console: Memorystore → Redis (if using a managed instance).

CLI:

redis-cli -h <redis-host> ping
# Confirm the injected cache/redis env in the running revision:
gcloud run services describe <service-name> --region "$REGION" \
  --format='value(spec.template.spec.containers[0].env)'

E. Secret Manager

One cryptographic secret is generated automatically and stored in Secret Manager: CP_ANALYTICS_SALT (used to anonymise podcast listener analytics). The database password is managed separately by the foundation.

Console: Security → Secret Manager.

CLI:

gcloud secrets list --project "$PROJECT" --filter="name~analytics-salt"
gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

See App_CloudRun for injection and rotation details.

F. Networking & ingress

The service is reachable at its run.app URL by default, which allows public access required for public podcast feeds and media downloads. An external HTTPS load balancer with a custom domain, Cloud CDN, and Cloud Armor can be layered on; ingress settings and VPC egress control connectivity.

Console: Cloud Run (service URL); Network services → Load balancing.

CLI:

gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
gcloud compute addresses list --project "$PROJECT"

See App_CloudRun.

G. Cloud Logging & Monitoring

Container logs flow to Cloud Logging; Cloud Run and Cloud SQL metrics flow to Cloud Monitoring, with optional uptime checks and alert policies.

Console: Logging → Logs Explorer; Monitoring → Dashboards / Alerting.

CLI:

gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. Castopod Application Behaviour

First-deploy database setup. An initialization Job runs db-init.sh using mysql:8.0-debian. It connects through the Cloud SQL Auth Proxy socket (or private-IP TCP fallback) and idempotently creates the application database and user, grants privileges, and verifies the app user can connect. The job is safe to re-run.
Migrations run on container start. The castopod/castopod image runs the CodeIgniter 4 schema migrations automatically on every startup, so the schema is created on first boot and upgrading the application version applies schema changes without a separate migration job.
Database config lives in .env, injected at runtime. The entrypoint writes database.default.hostname|database|username|password|port and app.baseURL into Castopod's .env from the foundation-injected DB_* and CLOUDRUN_SERVICE_URL values. It resolves the DB host to the private-IP TCP address because CI4's mysqli driver cannot use the Cloud SQL socket directory.
CP_ANALYTICS_SALT should be stable after first boot. It is generated once and written to Secret Manager; changing it breaks de-duplication continuity for previously recorded listeners. Only rotate deliberately.
Health path. The startup probe is TCP on the container port and the liveness probe is HTTP GET / — Castopod's unauthenticated homepage returns 200 once booted and connected to MySQL. Allow several minutes on first boot for the CodeIgniter migrations to complete (the startup probe provides a 30-second initial delay plus a 20-retry window).
First-run setup. After deploy, open the service URL and complete Castopod's web install wizard to create the first super-admin account and set the instance name and podcast defaults. Media uploads then persist to the NFS-backed media directory.

Inspect job execution:

gcloud run jobs list --project "$PROJECT" --region "$REGION"
gcloud run jobs executions list --job <job-name> --project "$PROJECT" --region "$REGION"

4. Configuration Variables

Variables are grouped exactly as they appear on the deployment platform. Only settings specific to or notable for Castopod are listed; every other input is inherited from App_CloudRun with its standard behaviour.