Deployment Guide

Overview

Merlin is deployed on Google Cloud Platform in the europe-west1 region:

API requests from the frontend are proxied through Firebase Hosting rewrites (/api/** routes to Cloud Run), so the frontend only talks to merlin-app.web.app.

Prerequisites

• gcloud CLI installed and authenticated as mrboups@gmail.com
• firebase CLI installed and authenticated
• Docker installed (for backend image builds)
• Node.js 22+ and pnpm (for frontend builds)
• Python 3.12 (for local backend development)

Verify your setup:

gcloud auth list                  # Must show mrboups@gmail.com as ACTIVE
gcloud config get-value project   # Must show merlin-wallet-prod
firebase projects:list            # Must show merlin-wallet-prod

GCP Project Details

Environment Variables

Copy .env.example to .env and fill in real values. Never commit .env to version control.

Deployment Safety Protocol (MANDATORY)

Before running ANY deploy command (gcloud builds submit, gcloud run deploy, firebase deploy, docker push), you MUST complete all of these checks:

1. Read .env and extract GCP_PROJECT_ID and GCP_ACCOUNT
2. Verify gcloud account matches:

   gcloud auth list
   # Active account MUST be mrboups@gmail.com

1. Verify gcloud project matches:

   gcloud config get-value project
   # MUST return merlin-wallet-prod

1. Verify Firebase account (for Firebase deploys):

   firebase login:list
   # MUST show mrboups@gmail.com

1. Always use explicit flags:

• --project merlin-wallet-prod
• --region europe-west1

1. If ANY mismatch: STOP. Do not proceed. Ask the operator to fix the configuration.
2. Never deploy to a project that does not match .env values.

This protocol exists to prevent accidental deployment to the wrong GCP project.

---

Deploy Backend (Cloud Run)

The backend is a FastAPI application packaged as a Docker container and deployed to Cloud Run.

Option 1: Docker Build + Deploy

Build the image locally, push to Artifact Registry, then deploy:

# Build the Docker image
docker build -t europe-west1-docker.pkg.dev/merlin-wallet-prod/merlin-docker/merlin-api:latest .

# Push to Artifact Registry
docker push europe-west1-docker.pkg.dev/merlin-wallet-prod/merlin-docker/merlin-api:latest

# Deploy to Cloud Run
gcloud run deploy merlin-api \
  --project merlin-wallet-prod \
  --region europe-west1 \
  --image europe-west1-docker.pkg.dev/merlin-wallet-prod/merlin-docker/merlin-api:latest \
  --allow-unauthenticated \
  --set-secrets="ETH_RPC_URL=ETH_RPC_URL:latest,SEPOLIA_RPC_URL=SEPOLIA_RPC_URL:latest,ANTHROPIC_API_KEY=ANTHROPIC_API_KEY:latest,GROK_API_KEY=GROK_API_KEY:latest"

Option 2: Cloud Build

Let Cloud Build handle the image build and push:

gcloud builds submit \
  --project merlin-wallet-prod \
  --region europe-west1

This uses the cloudbuild.yaml (if present) or the Dockerfile in the project root.

Cloud Run Configuration

Key settings for the merlin-api service:

Secret Manager Integration

Cloud Run accesses secrets via --set-secrets flag, which mounts Secret Manager values as environment variables at runtime. Available secrets:

# List all secrets
gcloud secrets list --project=merlin-wallet-prod

# Add or update a secret value
echo -n "YOUR_VALUE" | gcloud secrets versions add SECRET_NAME \
  --data-file=- \
  --project=merlin-wallet-prod

# View secret metadata (not the value)
gcloud secrets describe SECRET_NAME --project=merlin-wallet-prod

# Access a secret value (for debugging only)
gcloud secrets versions access latest --secret=SECRET_NAME --project=merlin-wallet-prod

Current secrets: ETH_RPC_URL, SEPOLIA_RPC_URL, ANTHROPIC_API_KEY, GROK_API_KEY.

---

Deploy Frontend (Firebase Hosting)

The frontend is a Next.js 15 app with static export, deployed to Firebase Hosting.

Build and Deploy

# Navigate to frontend directory
cd frontend

# Install dependencies
pnpm install

# Build the static export (outputs to frontend/out/)
pnpm build

# Deploy to Firebase Hosting
firebase deploy --only hosting:merlin-app --project merlin-wallet-prod

Firebase Configuration Files

firebase.json -- Hosting configuration with API proxy rewrites:

{
  "hosting": {
    "site": "merlin-app",
    "public": "frontend/out",
    "rewrites": [
      {
        "source": "/api/**",
        "run": {
          "serviceId": "merlin-api",
          "region": "europe-west1"
        }
      },
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

The /api/** rewrite routes all API calls from the frontend to the Cloud Run backend. This eliminates CORS issues and keeps the backend URL internal.

.firebaserc -- Project alias:

{
  "projects": {
    "default": "merlin-wallet-prod"
  }
}

firestore.rules -- Security rules enforce user-scoped read/write access. Users can only read and write their own documents.

Preview Before Deploy

To verify changes before deploying to production:

# Preview channel (temporary URL, auto-expires)
firebase hosting:channel:deploy preview --project merlin-wallet-prod

# This creates a URL like:
# https://merlin-app--preview-abc123.web.app

---

Firestore

Firestore is in Native mode in europe-west1. Collections:

Security rules ensure users can only access their own documents. The backend uses a service account with full access.

Deploy Firestore Rules

firebase deploy --only firestore:rules --project merlin-wallet-prod

---

Service URLs

---

Local Development

Backend

cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate       # Windows

# Install dependencies
pip install -r requirements.txt

# Run with hot reload
uvicorn main:app --reload --port 8000

# API available at http://localhost:8000
# Swagger docs at http://localhost:8000/docs

The backend reads environment variables from .env in the project root.

Frontend

cd frontend

# Install dependencies
pnpm install

# Run dev server
pnpm dev

# Available at http://localhost:3000
# API calls proxy to http://localhost:8000 via Next.js rewrites

Running Both Together

Start the backend and frontend in separate terminals. The frontend Next.js dev server proxies /api/** requests to http://localhost:8000, matching the Firebase Hosting rewrite behavior in production.

---

Monitoring and Logs

Cloud Run Logs

# Stream live logs
gcloud run services logs read merlin-api \
  --project merlin-wallet-prod \
  --region europe-west1 \
  --limit 100

# Tail logs in real time
gcloud run services logs tail merlin-api \
  --project merlin-wallet-prod \
  --region europe-west1

Cloud Run Metrics

View request count, latency, and error rates in the GCP Console:

https://console.cloud.google.com/run/detail/europe-west1/merlin-api/metrics?project=merlin-wallet-prod

Firebase Hosting

View hosting release history and traffic in the Firebase Console:

https://console.firebase.google.com/project/merlin-wallet-prod/hosting/sites/merlin-app

---

CI/CD (Planned)

GitHub Actions pipeline for automated deployment:

Trigger

• Push to main branch
• Pull request (lint + test only, no deploy)

Pipeline Steps

1. Lint and typecheck

• pnpm lint (frontend)
• pnpm typecheck (frontend)
• Python linting (backend)

1. Run tests

• pnpm test (frontend/SDK)
• pytest (backend)

1. Build and push Docker image

• Build from Dockerfile
• Push to europe-west1-docker.pkg.dev/merlin-wallet-prod/merlin-docker/merlin-api:$SHA
• Tag as :latest

1. Deploy backend to Cloud Run

• gcloud run deploy merlin-api --image ...:$SHA
• Uses Workload Identity Federation (no service account keys)

1. Build frontend

• pnpm build (Next.js static export)

1. Deploy frontend to Firebase Hosting

• firebase deploy --only hosting:merlin-app

Required GitHub Secrets

---

Rollback

Backend Rollback

Cloud Run keeps revision history. Roll back to a previous revision:

# List revisions
gcloud run revisions list \
  --service merlin-api \
  --project merlin-wallet-prod \
  --region europe-west1

# Route all traffic to a previous revision
gcloud run services update-traffic merlin-api \
  --project merlin-wallet-prod \
  --region europe-west1 \
  --to-revisions REVISION_NAME=100

Frontend Rollback

Firebase Hosting keeps release history. Roll back via the Firebase Console or CLI:

# List recent releases
firebase hosting:channel:list --project merlin-wallet-prod

# Roll back to a previous version (use the version ID from the console)
firebase hosting:clone merlin-app:VERSION_ID merlin-app:live --project merlin-wallet-prod

---

Cost Management

Key cost drivers and controls:

Prune Old Docker Images

# List images
gcloud artifacts docker images list \
  europe-west1-docker.pkg.dev/merlin-wallet-prod/merlin-docker \
  --project merlin-wallet-prod

# Delete a specific image digest
gcloud artifacts docker images delete \
  europe-west1-docker.pkg.dev/merlin-wallet-prod/merlin-docker/merlin-api@sha256:DIGEST \
  --project merlin-wallet-prod