beardrive/deploy/README.md

Deploy BearDrive to Google Cloud (Cloud Run)

Single-instance hub on Cloud Run, metadata in Cloud SQL Postgres, blobs/journals in a GCS bucket. Matches Phase 0 of the managed PRD.

The current build is single-process: Cloud Run is pinned to max-instances=1 because the in-memory caches assume one writer. Do not raise it until the "stateless app" work (PRD §5.1) lands.

Architecture

      browser / bdrive CLI
              │  https
        ┌─────▼─────┐   metadata   ┌──────────────┐
        │ Cloud Run │◀────────────▶│  Cloud SQL   │  (accounts, orgs,
        │  bdrive   │  unix socket │  Postgres    │   projects, invites…)
        │ (1 inst.) │              └──────────────┘
        └─────┬─────┘
              │ ADC (runtime SA)
        ┌─────▼─────┐
        │    GCS    │  blobs/ + journal/  (file content + sync log)
        └───────────┘

Prerequisites

• gcloud installed and logged in (gcloud auth login).
• A billing account id (gcloud billing accounts list) if the script creates the project.
• Values: PROJECT_ID, ADMIN_EMAIL, ADMIN_DOMAIN (the rest have defaults).

Run it

From the repo root:

PROJECT_ID=beardrive-prod \
BILLING_ACCOUNT=0X0X0X-0X0X0X-0X0X0X \
ADMIN_EMAIL=you@runbear.io \
ADMIN_DOMAIN=runbear.io \
REGION=us-central1 \
bash example/deploy/gcp-cloudrun.sh

The script: creates/links the project → enables APIs → creates the GCS bucket and Cloud SQL instance → generates a DB password (stored in Secret Manager) → writes the hub config to a secret → builds the image from the repo Dockerfile via Cloud Build → deploys Cloud Run with the Cloud SQL socket, the config secret mounted at /config/config.json, and a dedicated runtime service account granted GCS + Cloud SQL access. It prints the service URL.

First-run: bootstrap the admin, then lock down

The hub ships invite-only by default, but a brand-new hub has no accounts, so the deploy config temporarily allows domain-gated self-signup (allowed_domains: [ADMIN_DOMAIN]). Steps:

1. Open the printed URL → Sign up as ADMIN_EMAIL (must be on ADMIN_DOMAIN). The account is active immediately and is a hub admin.
2. Create your org/projects and invite teammates from the UI.
3. Tighten to invite-only: edit the config secret to "allow_signup": false and redeploy:

   gcloud secrets versions access latest --secret bdrive-config > /tmp/c.json
   #   …set "allow_signup": false …
   gcloud secrets versions add bdrive-config --data-file=/tmp/c.json
   gcloud run services update bdrive --region "$REGION"   # picks up latest secret
   

Rough cost

• Cloud Run: scales to ~zero when idle (min-instances=1 keeps one warm; set --min-instances 0 to save more, at the cost of cold-start journal folding on first hit). ~$5–15/mo warm.
• Cloud SQL db-f1-micro: ~$8–15/mo (smallest shared-core tier).
• GCS: pay per GB stored + egress. Cheap for text. gcp-cloudrun.sh installs a Nearline-at-30-days lifecycle rule by default (LIFECYCLE=0 skips it) — see below for why it stops there.

Storage tiering

Every version of every file is retained forever, so stored bytes only ever grow while per-seat revenue stays flat. Aging objects down is the lever.

Prices below are us-central1 regional, verified 2026-08-03 — re-check before relying on them, GCP moves them.

Class	Storage $/GB/mo	Retrieval $/GB	Min duration
Standard	0.020	—	none
Nearline	0.010	0.01	30 days
Coldline	0.004	0.02	90 days
Archive	0.0012	0.05	365 days

Archive really is ~6% of Standard, and GCS serves every class at the same millisecond latency — there is no restore job to wait on. The catch is the retrieval fee, so the break-even is entirely about how often a given object is read. Writing r for reads per GB per month:

• Nearline beats Standard while r < 1.0/mo
• Coldline beats Nearline while r < 0.6/mo
• Archive beats Coldline while r < 0.09/mo (about once a year)

This is why the script stops at Nearline. The tempting assumption is that old blobs are cold because old versions are rarely opened. That is not true here: a device syncing a project for the first time downloads a blob for every put op in every peer journal — the entire history, not just the current file tree (internal/syncer pull). Measured on a 10-version file whose working tree is 1 KB, a fresh device pulls 10 KB.

So the read rate on old blobs tracks how often anyone adds a device, not how often anyone opens an old version. A team that adds or replaces roughly one device a month drives r ≈ 1, which makes Coldline a wash and Archive a straight bill increase.

Two consequences worth acting on, in this order:

1. The real lever is not the lifecycle policy. Making a first sync fetch only current-state blobs (history stays available on demand through the existing /blob?sha= route) cuts onboarding egress from "all history" to "the working tree" and makes old blobs genuinely cold — which is what makes Coldline and Archive safe to turn on afterwards. Until then the ladder is priced against a read pattern the sync engine does not have.
2. Egress scales with devices × total history, not with change volume, and every byte is relayed: blob reads have no presigned path (only remote.PutSigner exists — uploads can go direct to storage, downloads cannot), so they stream GCS → Cloud Run → client. Same-region GCS→Cloud Run transfer is free, so this is one egress charge, not two — but it does occupy the single max-instances=1 container for the whole transfer.

The lifecycle rule is applied bucket-wide rather than to blobs/ alone because journals live under the same per-project prefixes and a GCS lifecycle matchesPrefix cannot express */blobs/. That is safe: a peer journal is re-fetched only when the listing shows it grew, and one that grew was just rewritten, so it is Standard again.

Notes / limits (single-instance build)

• max-instances=1 is required. Metadata correctness depends on one writer.
• BDRIVE_HOME=/tmp is ephemeral on Cloud Run → the server's own device id regenerates on cold start (cosmetic in history). Mount a volume later to persist it.
• Large downloads/sync stream through Cloud Run (bounded by the request timeout, up to 60 min). Uploads go direct to storage when the backend can presign. See PRD §5.2 for offloading these at scale.
• Put a custom domain on the service via gcloud run domain-mappings (gives managed TLS).