← All articles

Why Cloud Run for Paperclip

Cloud Run is Google's serverless container platform. You push a Docker image, set your CPU/memory, and Google runs it. Auto-scaling means you're not paying for idle time, and the free tier is generous. The main consideration: Cloud Run containers have ephemeral filesystems, so persistent data requires an external database or volume mount.

Prerequisites

• Google Cloud account with billing enabled
• gcloud CLI installed and authenticated
• Docker installed locally

Step 1: Set up your project

# Install gcloud CLI if needed
# https://cloud.google.com/sdk/docs/install

gcloud auth login
gcloud projects create paperclip-prod --name="Paperclip Production"
gcloud config set project paperclip-prod

# Enable required APIs
gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  sqladmin.googleapis.com \
  secretmanager.googleapis.com

Step 2: Create Cloud SQL (PostgreSQL)

Paperclip needs a persistent database. Cloud Run's ephemeral filesystem won't work for SQLite.

gcloud sql instances create paperclip-db \
  --database-version=POSTGRES_15 \
  --tier=db-f1-micro \
  --region=us-central1 \
  --storage-size=10GB

gcloud sql databases create paperclip \
  --instance=paperclip-db

gcloud sql users create paperclip \
  --instance=paperclip-db \
  --password=YOUR_DB_PASSWORD

Get the connection name:

gcloud sql instances describe paperclip-db --format='value(connectionName)'
# Output: paperclip-prod:us-central1:paperclip-db

Step 3: Create a Dockerfile

FROM node:20-alpine

WORKDIR /app

RUN npm install -g paperclipai

RUN adduser -D paperclip
USER paperclip

EXPOSE 8080

CMD ["npx", "paperclipai", "server", "start", "--port", "8080", "--host", "0.0.0.0"]

Note: Cloud Run uses port 8080 by default.

Step 4: Store secrets in Secret Manager

# Create secrets
echo -n "your_db_password" | gcloud secrets create DB_PASSWORD --data-file=-
echo -n "$(openssl rand -hex 32)" | gcloud secrets create BETTER_AUTH_SECRET --data-file=-

Step 5: Build and push the container

# Build with Cloud Build (no local Docker needed)
gcloud builds submit --tag gcr.io/paperclip-prod/paperclip:latest

Or build locally and push:

docker build -t gcr.io/paperclip-prod/paperclip:latest .
docker push gcr.io/paperclip-prod/paperclip:latest

Step 6: Deploy to Cloud Run

gcloud run deploy paperclip \
  --image gcr.io/paperclip-prod/paperclip:latest \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --memory 1Gi \
  --cpu 1 \
  --min-instances 1 \
  --max-instances 3 \
  --port 8080 \
  --add-cloudsql-instances paperclip-prod:us-central1:paperclip-db \
  --set-env-vars NODE_ENV=production \
  --set-secrets BETTER_AUTH_SECRET=BETTER_AUTH_SECRET:latest \
  --set-env-vars DATABASE_URL="postgresql://paperclip:YOUR_DB_PASSWORD@/paperclip?host=/cloudsql/paperclip-prod:us-central1:paperclip-db"

Key flags:

• --min-instances 1 — keeps one instance warm so Paperclip agents don't cold-start
• --add-cloudsql-instances — mounts the Cloud SQL proxy so your app can connect via Unix socket

Step 7: Custom domain

gcloud run domain-mappings create \
  --service paperclip \
  --domain paperclip.yourdomain.com \
  --region us-central1

Follow the DNS instructions Cloud Run returns. SSL is managed automatically.

Step 8: Verify the deployment

gcloud run services describe paperclip --region us-central1

Open the service URL (ends in .run.app) in your browser. Complete the Paperclip admin setup wizard.

Always-on configuration

For Paperclip agents to fire heartbeats reliably, set --min-instances 1. Without this, Cloud Run may scale to zero and your agents will miss scheduled runs.

gcloud run services update paperclip \
  --min-instances 1 \
  --region us-central1

Logs and monitoring

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=paperclip" \
  --limit=50 \
  --format="table(timestamp, textPayload)"

Or use Cloud Console → Cloud Run → paperclip → Logs.

Updating Paperclip

Rebuild and push the image, then update the revision:

gcloud builds submit --tag gcr.io/paperclip-prod/paperclip:latest
gcloud run deploy paperclip \
  --image gcr.io/paperclip-prod/paperclip:latest \
  --region us-central1

Cost estimate

• Cloud Run: ~$0/month if under 2M requests/month (generous free tier). Min-instances = 1 adds ~$10–15/month for always-on CPU.
• Cloud SQL db-f1-micro: ~$10/month
• Total: ~$20–25/month

For simpler setups with less configuration, Railway gives you $20 free credit and deploys Paperclip from a container in minutes.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.