managarten/apps/cards/DEPLOYMENT_CHECKLIST.md

Cards Backend Deployment Checklist

This checklist ensures you have everything configured for automated deployment.

✅ Prerequisites

1. GitHub Secrets (Required)

Go to https://github.com/Memo-2023/cards → Settings → Secrets and variables → Actions

Add these secrets:

Secret Name	Description	How to Get
GCP_SA_KEY_PROD	Service account JSON key for Cloud Run deployment	See "Create Service Account" below
CLOUD_RUN_SERVICE_ACCOUNT	Service account email	cards-backend-sa@memo-2c4c4.iam.gserviceaccount.com
GH_PERSONAL_TOKEN	GitHub Personal Access Token for private packages	See "Create GitHub PAT" below

Create Service Account

# 1. Create service account
gcloud iam service-accounts create cards-backend-sa \
  --display-name="Cards Backend Service Account" \
  --project=memo-2c4c4

# 2. Grant permissions
SA_EMAIL="cards-backend-sa@memo-2c4c4.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding memo-2c4c4 \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding memo-2c4c4 \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding memo-2c4c4 \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/artifactregistry.writer"

# 3. Create and download key
gcloud iam service-accounts keys create cards-sa-key.json \
  --iam-account=${SA_EMAIL} \
  --project=memo-2c4c4

# 4. Copy contents of cards-sa-key.json to GCP_SA_KEY_PROD secret
cat cards-sa-key.json

# 5. Delete local key file (security best practice)
rm cards-sa-key.json

Create GitHub Personal Access Token

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Name: Cards CI/CD
4. Expiration: Choose appropriate timeframe
5. Scopes: Select repo (Full control of private repositories)
6. Click "Generate token"
7. Copy token and add to GH_PERSONAL_TOKEN secret

2. GCP Artifact Registry

# Create repository for Docker images
gcloud artifacts repositories create cards-backend \
  --repository-format=docker \
  --location=europe-west3 \
  --project=memo-2c4c4 \
  --description="Docker images for Cards Backend"

3. GCP Secrets (Required)

Run the interactive script:

cd backend
./create-secrets.sh

Or create manually:

# All secrets go to mana-core-453821 project
PROJECT_ID="mana-core-453821"

# Generate service key
SERVICE_KEY=$(openssl rand -base64 32)

# Create secrets
echo "your-app-id" | gcloud secrets create CARDS_APP_ID --data-file=- --project=$PROJECT_ID
echo "$SERVICE_KEY" | gcloud secrets create CARDS_SERVICE_KEY --data-file=- --project=$PROJECT_ID
echo "https://xxx.supabase.co" | gcloud secrets create CARDS_SUPABASE_URL --data-file=- --project=$PROJECT_ID
echo "your-anon-key" | gcloud secrets create CARDS_SUPABASE_ANON_KEY --data-file=- --project=$PROJECT_ID
echo "your-service-key" | gcloud secrets create CARDS_SUPABASE_SERVICE_KEY --data-file=- --project=$PROJECT_ID
echo "https://app.com/welcome" | gcloud secrets create CARDS_SIGNUP_REDIRECT_URL --data-file=- --project=$PROJECT_ID

# Grant access to service account
SA_EMAIL="cards-backend-sa@memo-2c4c4.iam.gserviceaccount.com"

for SECRET in MANA_SERVICE_URL CARDS_APP_ID CARDS_SERVICE_KEY CARDS_SUPABASE_URL CARDS_SUPABASE_ANON_KEY CARDS_SUPABASE_SERVICE_KEY CARDS_SIGNUP_REDIRECT_URL; do
  gcloud secrets add-iam-policy-binding $SECRET \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="roles/secretmanager.secretAccessor" \
    --project=$PROJECT_ID
done

IMPORTANT: Add the generated SERVICE_KEY to mana-middleware's APP_SERVICE_KEYS:

APP_SERVICE_KEYS=existing-apps,YOUR_APP_ID:YOUR_SERVICE_KEY

🚀 Deployment Process

Automatic Deployment (GitHub Actions)

1. Push to main branch:

   git add .
   git commit -m "feat: your changes"
   git push origin main
   

2. GitHub Actions will automatically:

   • ✅ Run tests and linting
   • ✅ Build Docker image
   • ✅ Push to Artifact Registry
   • ✅ Deploy to Cloud Run
   • ✅ Run health checks
   • ✅ Rollback on failure

3. Monitor deployment:

   • Go to https://github.com/Memo-2023/cards/actions
   • View workflow run progress

Manual Deployment (Cloud Build)

cd backend

# Update version in cloudbuild.yaml (e.g., v1.0.0 → v1.0.1)

# Build and push
gcloud builds submit --project=memo-2c4c4 --config=cloudbuild.yaml .

# Deploy
gcloud run deploy cards-backend \
  --image=europe-west3-docker.pkg.dev/memo-2c4c4/cards-backend/cards-backend:v1.0.1 \
  --project=memo-2c4c4 \
  --region=europe-west3

🔍 Verification

Check Deployment Status

# Get service URL
gcloud run services describe cards-backend \
  --project=memo-2c4c4 \
  --region=europe-west3 \
  --format='value(status.url)'

# Test health endpoint
curl https://cards-backend-xxx.run.app/health

# Test liveness
curl https://cards-backend-xxx.run.app/health/live

View Logs

# Recent logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=cards-backend" \
  --project=memo-2c4c4 \
  --limit=50

# Error logs only
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=cards-backend AND severity>=ERROR" \
  --project=memo-2c4c4 \
  --limit=20

🔧 Troubleshooting

GitHub Actions Fails with "npm ci" Error

Problem: Private package @mana-core/nestjs-integration can't be installed

Solution: Verify GH_PERSONAL_TOKEN secret is set with repo scope

Deployment Fails with "Permission Denied" on Secrets

Problem: Service account can't access secrets in mana-core-453821

Solution: Grant cross-project secret access:

SA_EMAIL="cards-backend-sa@memo-2c4c4.iam.gserviceaccount.com"

gcloud secrets add-iam-policy-binding CARDS_APP_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/secretmanager.secretAccessor" \
  --project=mana-core-453821

Health Check Fails After Deployment

Problem: Service starts but health endpoint returns 500

Possible causes:

1. Missing environment variables/secrets
2. Can't connect to Supabase
3. Can't connect to Mana

Debug:

# Check service logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=cards-backend" \
  --project=memo-2c4c4 \
  --limit=20

# Check secret values (if you have permissions)
gcloud secrets versions access latest --secret=CARDS_APP_ID --project=mana-core-453821

Peer Dependency Warning

Problem: @mana-core/nestjs-integration has peer dependency on @nestjs/common@^10.0.0 but project uses ^11.0.0

Solution: Already handled with --legacy-peer-deps flag in workflow. If you see this locally:

npm install --legacy-peer-deps

📊 Project Structure

cards/
├── .github/
│   └── workflows/
│       └── deploy-backend.yml        # GitHub Actions workflow
├── backend/
│   ├── src/                          # Source code
│   ├── Dockerfile                    # Container definition
│   ├── cloudbuild.yaml              # Manual deployment config
│   ├── create-secrets.sh            # Interactive secrets setup
│   ├── verify-build.sh              # Local build verification
│   ├── DEPLOY_MANUAL.md             # Detailed deployment docs
│   └── package.json
├── apps/
│   ├── mobile/
│   ├── web/
│   └── landing/
└── DEPLOYMENT_CHECKLIST.md          # This file

📝 Configuration Summary

Component	Location	Value
Deployment Project	GCP	memo-2c4c4
Secrets Project	GCP	mana-core-453821
Region	GCP	europe-west3
Service Name	Cloud Run	cards-backend
Image Registry	Artifact Registry	europe-west3-docker.pkg.dev/memo-2c4c4/cards-backend
Port	Container	8080
Repository	GitHub	Memo-2023/cards

🎯 Quick Start

First-time setup:

# 1. Create GCP resources
./backend/create-secrets.sh

# 2. Add GitHub secrets (see "GitHub Secrets" section)

# 3. Push to trigger deployment
git push origin main

After setup:

# Just push to deploy
git add .
git commit -m "feat: your changes"
git push origin main

---

Last Updated: 2025-09-30 Maintainer: Development Team