​

Songbird Headless DAW — Cloud Run Deployment

​

Architecture

                        ┌─ X-API-Key header ─┐
                        │  or ?api_key= param │
                        └────────┬────────────┘
                                 │
┌────────────────────────────────▼────────────────────────────┐
│  Cloud Run Container (gen2, spot, concurrency=1)            │
│                                                              │
│  ┌───────────┐   ┌──────────────┐   ┌───────────┐          │
│  │   Nginx   │──▶│ Headless DAW │   │  Collab   │          │
│  │   :8080   │   │  WS :9090    │   │  WS :8765 │          │
│  │ (API key  │──▶│  HTTP :9091  │   │           │          │
│  │  + proxy) │   └──────────────┘   └───────────┘          │
│  │           │                                              │
│  │           │──▶┌──────────────┐                           │
│  │           │   │ Clone Svc    │                           │
│  │           │   │  HTTP :9092  │                           │
│  └───────────┘   └──────────────┘                           │
│       │                │                                     │
│       │         ┌──────┴──────┐   ┌──────────────┐          │
│       │         │  GCS Fuse   │   │  GCS Fuse    │          │
│       │         │ /data/proj  │   │ /data/repos  │          │
│       │         └──────┬──────┘   └──────┬───────┘          │
└───────│────────────────│────────────────│────────────────────┘
        │                │                │
        ▼                ▼                ▼
   daw.club         GCS Bucket       GCS Bucket
   (React UI)    (project files)  (gitea bare repos)

• API key authentication — All routes except /healthz require a valid SONGBIRD_API_KEY via X-API-Key header or ?api_key= query param
• Spot instances — ~60-91% cheaper than standard Cloud Run
• GCS Fuse — Project files (.bird, audio samples) mounted as a filesystem
• 1 user per instance — Each DAW session gets a dedicated container (concurrency=1)
• Scale to zero — No cost when idle
• Session affinity — Sticky WebSocket connections for the duration of a session
• 60-minute timeout — Long-lived WebSocket sessions supported

​

Launch Flow (daw.club → VM)

1. daw.club opens https://vm.daw.club?repo=<clone_url>&api_key=<key> in a new tab
2. The React UI loads and detects the ?repo= query parameter
3. React UI calls POST /api/clone with { "url": "<clone_url>" } — the clone service finds the bare repo on the GCS Fuse mount at /data/repos/<owner>/<repo>.git and does a fast local checkout to /tmp/songbird-session/
4. React UI connects to the headless DAW via WebSocket (/ws)
5. React UI calls projectChoice("openRecent:<cloned_path>") to load the project

​

Gitea Setup (one-time)

# 1. Create the GCS bucket
gcloud storage buckets create gs://songbird-gitea-repos --location=us-central1

# 2. Install GCS Fuse on the Gitea VM
sudo apt-get install gcsfuse

# 3. Mount the bucket
sudo mkdir -p /data/gitea-repos
sudo gcsfuse --implicit-dirs songbird-gitea-repos /data/gitea-repos

# 4. Move existing repos to the mount
sudo rsync -a /var/lib/gitea/data/gitea-repositories/ /data/gitea-repos/

# 5. Update Gitea config (/etc/gitea/app.ini)
#    [repository]
#    ROOT = /data/gitea-repos

# 6. Restart Gitea
sudo systemctl restart gitea

# 7. Grant Cloud Run service account read access
PROJECT_NUMBER=$(gcloud projects describe gen-lang-client-0380481603 --format="value(projectNumber)")
gcloud storage buckets add-iam-policy-binding gs://songbird-gitea-repos \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

​

Current Deployment State

​

Load Balancer (Public Access)

# Should return 200 (no auth required for healthz)
curl http://34.111.95.214/healthz

# Should return 403 (no API key)
curl http://34.111.95.214/ws

# Should return 200 (API key via header)
curl -H "X-API-Key: $SONGBIRD_API_KEY" http://34.111.95.214/healthz

# Should return 426 (WebSocket upgrade required — means auth passed)
curl -H "X-API-Key: $SONGBIRD_API_KEY" http://34.111.95.214/ws

​

Prerequisites

1. GCP project with billing enabled
2. gcloud CLI authenticated (gcloud auth login)
3. APIs enabled:
   gcloud services enable \
       run.googleapis.com \
       cloudbuild.googleapis.com \
       artifactregistry.googleapis.com \
       storage.googleapis.com \
       --project=gen-lang-client-0380481603
   
4. Git submodules initialized (the Docker build copies the full source tree):
   git submodule update --init --recursive
   

​

Quick Deploy

# From the repo root:
./deploy/cloud-run/deploy.sh

1. Create a GCS bucket for project storage (if it doesn’t exist)
2. Grant the Cloud Run service account access to the bucket
3. Build the Docker image via Cloud Build (~35 min for full C++ build)
4. Deploy to Cloud Run with spot instances + GCS Fuse
5. Set up API key authentication (auto-generates a key if SONGBIRD_API_KEY is not set)
6. Attempt allUsers IAM binding (gracefully skipped if org policy blocks it)

​

Skip-Build Mode (~2 min instead of ~35 min)

SONGBIRD_API_KEY="your-key" ./deploy/cloud-run/deploy.sh --skip-build --version v1.0.1

​

Configuration

MEMORY=4Gi CPU=4 MAX_INSTANCES=20 ./deploy/cloud-run/deploy.sh

​

API Key Authentication

​

Why API keys?

​

How it works

1. deploy.sh auto-generates a random key via python3 -c 'import secrets; print(secrets.token_urlsafe(32))' if SONGBIRD_API_KEY env var is not set
2. The key is passed to the Cloud Run service as an environment variable
3. entrypoint.sh validates the key at startup:
   • Refuses to start if SONGBIRD_API_KEY is empty (prevents '' = '' nginx bypass)
   • Refuses to start if key is the placeholder REPLACE_WITH_API_KEY
4. entrypoint.sh passes the key to envsubst which substitutes it into nginx.conf
5. nginx.conf checks every request (except /healthz) for a valid key via:
   • X-API-Key header
   • ?api_key= query parameter
6. Returns 403 {"error":"invalid api key"} on mismatch

​

Security considerations

• The API key is stored as a Cloud Run env var (visible in GCP console and gcloud run services describe). For higher security, use Secret Manager with valueFrom.secretKeyRef.
• Nginx if directives don’t inherit into nested location blocks — each location has its own auth check.
• The /healthz endpoint is intentionally unauthenticated (Cloud Run startup/liveness probes need it).
• The allUsers IAM binding attempt is still made but gracefully falls back if org policy blocks it.

​

Frontend integration

https://daw.club?ws=songbird-headless-6kdcepjumq-uc.a.run.app/ws&api_key=YOUR_KEY

const ws = new WebSocket('wss://songbird-headless-6kdcepjumq-uc.a.run.app/ws', [], {
  headers: { 'X-API-Key': 'YOUR_KEY' }
});

​

Build Architecture

┌─────────────────────────────────────────────────────┐
│ ARG BUILDER_STAGE=full|prebuilt                     │
│                                                      │
│ ┌─────────────────┐   ┌─────────────────────┐      │
│ │ builder-full    │   │ builder-prebuilt     │      │
│ │ (C++ compile    │   │ (COPY from build     │      │
│ │  ~35 min)       │   │  context, ~1 sec)    │      │
│ └────────┬────────┘   └──────────┬──────────┘      │
│          │   selected by ARG     │                   │
│          └──────────┬────────────┘                   │
│                     ▼                                │
│          ┌──────────────────┐                        │
│          │ builder (alias)  │                        │
│          └────────┬─────────┘                        │
│                   │                                  │
│ ┌─────────────────┼─────────────────┐               │
│ │                 │                 │               │
│ ▼                 ▼                 ▼               │
│ react-ui      runtime           runtime             │
│ (vite build)  COPY binary       COPY static         │
│               + nginx + node    + entrypoint        │
└─────────────────────────────────────────────────────┘

• builder-full: Ubuntu 22.04, installs build-essential + JUCE deps, runs cmake + make with -j2 (avoids OOM)
• builder-prebuilt: Copies binary from deploy/cloud-run/prebuilt/SongbirdHeadless (placed there by deploy.sh --skip-build)
• react-ui: Node 20, runs npm ci + npx vite build (skips tsc — pre-existing TS errors on headless branch)
• runtime: Ubuntu 22.04 with nginx, Node.js 20, Xvfb, GCS Fuse, tini (PID 1)

​

Cloud Build

gcloud builds submit \
  --tag=us-central1-docker.pkg.dev/gen-lang-client-0380481603/songbird/songbird-headless:v1.0.1 \
  --timeout=3600 --machine-type=e2-highcpu-8 \
  --region=us-central1 .

​

Binary upload to GCS

gs://songbird-daw-club-repos/bin/v1.0.0/SongbirdHeadless-release
gs://songbird-daw-club-repos/bin/latest/SongbirdHeadless-release

​

Manual Deploy

​

1. Build the Docker image

# Option A: Full build with Cloud Build (~35 min)
gcloud builds submit \
  --tag=us-central1-docker.pkg.dev/gen-lang-client-0380481603/songbird/songbird-headless:latest \
  --timeout=3600 --machine-type=e2-highcpu-8 --region=us-central1 .

# Option B: Build locally (needs Docker + 8GB+ RAM)
docker build -t us-central1-docker.pkg.dev/gen-lang-client-0380481603/songbird/songbird-headless .
docker push us-central1-docker.pkg.dev/gen-lang-client-0380481603/songbird/songbird-headless

​

2. Deploy to Cloud Run

• Update the image: tag to your version
• Update the SONGBIRD_API_KEY value (do NOT leave it as REPLACE_WITH_API_KEY)
• Update bucketName if using a different GCS bucket

gcloud run services replace deploy/cloud-run/service.yaml \
  --project=gen-lang-client-0380481603 --region=us-central1

# Attempt public access (may be blocked by org policy — that's OK, API key handles auth)
gcloud run services add-iam-policy-binding songbird-headless \
  --project=gen-lang-client-0380481603 --region=us-central1 \
  --member="allUsers" --role="roles/run.invoker"

​

3. Upload a project

gcloud storage cp myproject.bird gs://songbird-projects-gen-lang-client-0380481603/

​

4. Connect from the React UI

https://daw.club?ws=songbird-headless-6kdcepjumq-uc.a.run.app/ws&api_key=YOUR_KEY

​

GCP Authentication Notes

export CLOUDSDK_AUTH_ACCESS_TOKEN="ya29...."

• gcloud storage cp instead of gsutil cp
• gcloud storage ls instead of gsutil ls
• gcloud storage buckets create instead of gsutil mb

​

Container Ports

• /ws → headless DAW WebSocket (:9090) — requires API key
• /resources/ → headless DAW HTTP resources (:9091) — requires API key
• /collab → collaboration server (:8765) — requires API key
• /api/clone → clone service (:9092) — requires API key
• /healthz → health check (nginx responds directly) — no auth
• / → React UI static files — requires API key

​

Container Startup Sequence

1. Validate API key — exit if empty or placeholder
2. GCS Fuse mount — only for local Docker runs; Cloud Run uses CSI driver
3. Xvfb — virtual framebuffer (JUCE/GTK needs a display even headless)
4. SongbirdHeadless — the C++ binary (WS :9090, HTTP :9091)
5. Collab server — Node.js WebSocket server (:8765)
6. Clone service — Node.js HTTP server for git clone API (:9092)
7. Wait for readiness — polls headless HTTP port for up to 15 seconds
8. Nginx — reverse proxy with API key auth (:8080)

​

Cost Estimate

​

Troubleshooting

​

Container won’t start

• Check logs: gcloud run services logs read songbird-headless --region=us-central1
• If you see FATAL: SONGBIRD_API_KEY is not set — the env var is missing from the service config
• If you see FATAL: SONGBIRD_API_KEY is still set to the placeholder value — update the key in service.yaml
• The headless binary needs Xvfb (virtual framebuffer) — included in the Docker image
• GTK/WebKit runtime libs must be present — see Dockerfile runtime stage

​

403 on all requests

• Verify SONGBIRD_API_KEY is set correctly in the Cloud Run service config
• Check you’re passing the key via X-API-Key header or ?api_key= query param
• The /healthz endpoint should always return 200 without auth — if it returns 403, the nginx config is wrong

​

GCS Fuse mount fails

• Ensure the Cloud Run service account has storage.objectAdmin on the bucket
• GCS Fuse requires gen2 execution environment (set in service.yaml)
• Check mount logs in container stderr

​

WebSocket connection drops

• Cloud Run has a 60-minute request timeout (configured in service.yaml)
• Session affinity is enabled to maintain sticky connections
• If using a custom domain, ensure the load balancer supports WebSocket upgrade

​

Cloud Build times out

• Default timeout is 30 minutes — C++ builds need ~35 minutes
• Always use --timeout=3600 (60 min) for full builds
• Use --machine-type=e2-highcpu-8 for faster compilation
• Build uses -j2 to avoid OOM — don’t increase without more memory

​

Audio dropouts

• Increase CPU/memory: MEMORY=4Gi CPU=4 ./deploy/cloud-run/deploy.sh
• Cloud Run gen2 has better CPU performance than gen1
• Consider MIN_INSTANCES=1 to avoid cold starts during active use

​

Org policy blocks allUsers

• This is expected. The API key approach works without public IAM binding.
• The deploy script gracefully handles this: || echo "allUsers binding skipped"
• Do NOT try to relax the org policy — use the API key instead

​

Files Reference