Saltar al contenido principal

Pre-Deployment Checklist for Metabase

Use this checklist before deploying Metabase to ensure everything is ready.

✅ Prerequisites​

Phase 1: Infrastructure ✅​

  • Cloud SQL instances created (staging & production)
  • Databases and users created
  • Connection details documented

Phase 2: Code & Configuration ✅​

  • Dockerfile created (deploy/gcp/metabase.Dockerfile)
  • GitHub Actions workflow created (.github/workflows/deploy-metabase.yml)
  • Backend integration complete
  • Frontend components created

Phase 3: Secrets & Configuration ⚠️​

  • GitHub Secrets configured for staging environment:

    • METABASE_DB_TYPE=postgres
    • METABASE_DB_NAME=metabase
    • METABASE_DB_USER=metabase_user
    • METABASE_DB_PASS=<password>
    • METABASE_DB_CONNECTION=<connection-name>
    • METABASE_DB_CONNECTION_URI=<connection-uri>
    • METABASE_SITE_URL=<placeholder-url> (will update after deployment)
    • METABASE_EMBED_SECRET_KEY=<jwt-secret>
    • MB_ANON_TRACKING_ENABLED=false
    • MB_ENABLE_PUBLIC_SHARING=false
    • Backend config: METABASE_SITE_URL and METABASE_EMBED_SECRET_KEY

  • Doppler secrets configured for production:

    • Same as staging (with production values)

Reference: See docs/metabase/github-secrets-reference.md for complete list of required secrets.

Verify secrets:

  • Go to: Settings → Secrets and variables → Actions → staging
  • Go to: Settings → Secrets and variables → Actions → production
  • Check that all required secrets are set

🔧 Pre-Deployment Verification​

# Build locally to verify Dockerfile works
docker build -f deploy/gcp/metabase.Dockerfile -t metabase-test .

# Test the image runs (optional)
docker run -d -p 3000:3000 --name metabase-test metabase-test
sleep 30
curl http://localhost:3000/api/health
docker stop metabase-test && docker rm metabase-test

2. Verify Workflow Syntax​

# Check YAML syntax (if yamllint is installed)
yamllint .github/workflows/deploy-metabase.yml

3. Verify Artifact Registry Access​

The workflow will create the repository automatically, but you can verify access:

# For staging
gcloud artifacts repositories list --location=us-central1 --project=barto-dev

# For production
gcloud artifacts repositories list --location=us-central1 --project=barto-prod

4. Verify Cloud SQL Instances​

# Staging
gcloud sql instances describe metabase-db-staging \
  --project=barto-dev \
  --format="value(state)"

# Production
gcloud sql instances describe metabase-db-production \
  --project=barto-prod \
  --format="value(state)"

Both should return RUNNABLE.

5. Verify VPC Connectors​

# Staging
gcloud compute networks vpc-access connectors describe cloudrun-vpc-connector \
  --region=us-central1 \
  --project=barto-dev

# Production
gcloud compute networks vpc-access connectors describe barto-prod-vpc \
  --region=us-central1 \
  --project=barto-prod

🚀 Deployment Steps​

For Staging:​

  1. Create PR with all Metabase changes
  2. Verify workflow will trigger (check changed files)
  3. Merge PR to develop branch
  4. Monitor GitHub Actions workflow
  5. Verify deployment using ./scripts/verify-metabase-deployment.sh staging
  6. Update METABASE_SITE_URL in Doppler with actual URL
  7. Access Metabase UI and complete initial setup
  8. Connect to app database using ./scripts/get-metabase-db-connection.sh staging

For Production:​

  1. Verify staging deployment works correctly
  2. Create PR targeting main branch
  3. Merge PR to main branch
  4. Monitor GitHub Actions workflow
  5. Verify deployment using ./scripts/verify-metabase-deployment.sh production
  6. Update METABASE_SITE_URL in Doppler with actual URL
  7. Access Metabase UI and complete initial setup
  8. Connect to app database using ./scripts/get-metabase-db-connection.sh production

📋 Post-Deployment Checklist​

After successful deployment:

  • Service URL obtained and documented
  • METABASE_SITE_URL updated in Doppler (both Metabase and backend configs)
  • Metabase UI accessible
  • Health endpoint responds: curl <url>/api/health
  • Admin user created
  • Site settings configured
  • App database connected
  • Database sync verified
  • Tables visible in Metabase UI
  • business_id columns verified

🆘 Troubleshooting​

If deployment fails:

  1. Check Cloud Run logs:

    gcloud run services logs read flowpos-metabase-<env> \
      --region=us-central1 \
      --project=<project-id> \
      --limit=50

  2. Verify secrets are set:

    • Go to: Settings → Secrets and variables → Actions →
    • Check that all required Metabase secrets are present

  3. Check Cloud SQL instances:

    gcloud sql instances list --project=<project-id>

  4. Verify VPC connector:

    gcloud compute networks vpc-access connectors list \
      --region=us-central1 \
      --project=<project-id>

📚 Resources​

  • Deployment Guide: docs/metabase/deployment-guide.md
  • Quick Reference: docs/metabase/phase4-quick-reference.md
  • Implementation Plan: docs/metabase/implementation-plan.md
  • Secrets Reference: secrets/METABASE_SECRETS_REFERENCE.md