Saltar al contenido principal

Metabase Deployment Guide - Phase 4

This guide walks through deploying Metabase to Cloud Run for both staging and production environments.

Prerequisites Checklist​

Before starting deployment, ensure:

  • Phase 1: Infrastructure Setup (Cloud SQL instances created)
  • Phase 2: Code & Configuration (Dockerfile, workflow, backend, frontend)
  • Phase 3: Secrets & Configuration (Doppler secrets configured)
    • Run ./scripts/setup-metabase-doppler-secrets.sh staging
    • Run ./scripts/setup-metabase-doppler-secrets.sh production
    • Verify secrets: doppler secrets --project flowpos-workspace --config staging | grep METABASE

Phase 4.0: Domain Configuration Decision​

Decision Required: Choose one of the following:

Pros:

  • No DNS configuration needed
  • SSL certificates automatically provisioned
  • Faster initial deployment

Cons:

  • URLs are long and not user-friendly
  • Need to update METABASE_SITE_URL after first deployment

Action: Proceed with deployment, then update METABASE_SITE_URL in Doppler after getting the actual URL.

Option B: Custom Domain Mapping​

Pros:

  • Clean, branded URLs
  • Better for production

Cons:

  • Requires DNS configuration
  • SSL certificate provisioning takes time
  • More complex setup

Action: If choosing this option, configure DNS and domain mapping before deployment.

Recommendation: Start with Option A, then migrate to Option B if needed.

Phase 4.1: Deploy to Staging (barto-dev)​

Step 1: Verify Prerequisites​

# Verify Doppler secrets are set
doppler secrets --project flowpos-workspace --config staging | grep METABASE

# Verify workflow file exists
ls -la .github/workflows/deploy-metabase.yml

# Verify Dockerfile exists
ls -la deploy/gcp/metabase.Dockerfile
# Build the Docker image locally to verify it works
docker build -f deploy/gcp/metabase.Dockerfile -t metabase-test .

# Test the image runs
docker run -d -p 3000:3000 --name metabase-test metabase-test

# Check health endpoint
sleep 30  # Wait for Metabase to start
curl http://localhost:3000/api/health

# Clean up
docker stop metabase-test
docker rm metabase-test

Step 3: Create and Merge PR​

The workflow triggers on merged PRs to develop branch:

  1. Create a PR with Metabase changes (if not already merged):

    • Ensure all Phase 2 code is committed
    • Push to a feature branch
    • Create PR targeting develop branch

  2. Verify workflow will trigger:

    • Check that changed files include:
      • deploy/gcp/metabase.Dockerfile
      • .github/workflows/deploy-metabase.yml
    • Or any file in docs/metabase/ (if path filters include it)

  3. Merge PR to develop branch

Step 4: Monitor Deployment​

  1. Check GitHub Actions:

    • Go to: Actions → Deploy Metabase
    • Verify workflow runs after PR merge
    • Check for any errors

  2. Verify deployment steps:

    • Setup job completes successfully
    • Docker image builds and pushes to Artifact Registry
    • Cloud Run deployment succeeds
    • Service URL is displayed in workflow output

Step 5: Verify Deployment​

# Get the deployed service URL
SERVICE_URL=$(gcloud run services describe flowpos-metabase-staging \
  --region=us-central1 \
  --project=barto-dev \
  --format="value(status.url)")

echo "Metabase URL: $SERVICE_URL"

# Check health endpoint
curl "$SERVICE_URL/api/health"

# Check service status
gcloud run services describe flowpos-metabase-staging \
  --region=us-central1 \
  --project=barto-dev

Step 6: Update METABASE_SITE_URL in GitHub Secrets​

After getting the actual URL:

# Get the actual URL
ACTUAL_URL=$(gcloud run services describe flowpos-metabase-staging \
  --region=us-central1 \
  --project=barto-dev \
  --format="value(status.url)")

echo "Update METABASE_SITE_URL in GitHub Secrets:"
echo "Go to: Settings → Secrets and variables → Actions → staging"
echo "Update secret: METABASE_SITE_URL = $ACTUAL_URL"

Note: Also update METABASE_SITE_URL in backend GitHub Secrets (staging environment).

Step 7: Access Metabase UI​

  1. Open the Metabase URL in browser
  2. Complete initial setup:
    • Create admin user account
    • Configure site settings (name, timezone)
    • Set up email (optional)

Phase 4.2: Connect Metabase to App Database (Staging)​

Step 1: Access Metabase UI​

Navigate to: https://<your-metabase-staging-url>

Step 2: Add Database Connection​

  1. Go to: Settings → Admin → Databases → Add Database

  2. Database Type: PostgreSQL

  3. Name: FlowPOS Staging DB

  4. Connection Method: Using a connection string (recommended)

  5. Connection String:

    postgresql://flowpos_staging:<password>@/flowpos_staging?host=/cloudsql/barto-dev:us-central1:metabase-db-staging

    Note: Replace <password> with the actual password from Doppler staging config.

    To get the password:

    doppler secrets get DATABASE_URL_STAGING --project flowpos-workspace --config staging

    Extract the password from the connection string.

  6. Alternative: Manual Configuration

    • Host: /cloudsql/barto-dev:us-central1:metabase-db-staging (Unix socket path)
    • Port: 5432 (or leave empty for Unix socket)
    • Database name: flowpos_staging
    • Username: flowpos_staging
    • Password: [from Doppler staging config]
    • Additional JDBC connection string options: ?sslmode=disable

  7. Test Connection - Click "Test Connection"

  8. Save - Click "Save"

Step 3: Verify Database Sync​

  1. Wait for sync (may take several minutes):

    • Metabase will automatically sync database schema
    • Check sync status in: Settings → Admin → Databases

  2. Verify tables are visible:

    • Go to: Browse Data → FlowPOS Staging DB
    • Check that tables are listed

  3. Verify business_id columns:

    • Open a table (e.g., sale)
    • Verify business_id column exists

  4. Test a simple query:

    SELECT COUNT(*) FROM sale WHERE business_id IS NOT NULL;

Phase 4.3: Deploy to Production (barto-prod)​

Step 1: Verify Staging Deployment​

Ensure staging is working correctly before deploying to production.

Step 2: Create and Merge PR​

  1. Create a PR targeting main branch
  2. Merge PR to main branch

Step 3: Monitor Deployment​

Same as staging (Step 4 above), but check for production environment.

Step 4: Verify Deployment​

# Get the deployed service URL
SERVICE_URL=$(gcloud run services describe flowpos-metabase-production \
  --region=us-central1 \
  --project=barto-prod \
  --format="value(status.url)")

echo "Metabase URL: $SERVICE_URL"

# Check health endpoint
curl "$SERVICE_URL/api/health"

Step 5: Update METABASE_SITE_URL in GitHub Secrets​

# Get the actual URL
ACTUAL_URL=$(gcloud run services describe flowpos-metabase-production \
  --region=us-central1 \
  --project=barto-prod \
  --format="value(status.url)")

echo "Update METABASE_SITE_URL in GitHub Secrets:"
echo "Go to: Settings → Secrets and variables → Actions → production"
echo "Update secret: METABASE_SITE_URL = $ACTUAL_URL"

Note: Also update METABASE_SITE_URL in backend GitHub Secrets (production environment).

Step 6: Complete Initial Setup​

Same as staging (Step 7 above).

Phase 4.4: Connect Metabase to App Database (Production)​

Same steps as Phase 4.2, but:

  • Use production Metabase URL
  • Connection string: postgresql://flowpos_production:<password>@/flowpos_production?host=/cloudsql/barto-prod:us-central1:metabase-db-production
  • Database name: flowpos_production
  • Username: flowpos_production

Troubleshooting​

Deployment Fails​

  1. Check Cloud Run logs:

    gcloud run services logs read flowpos-metabase-staging \
      --region=us-central1 \
      --project=barto-dev \
      --limit=50

  2. Verify Cloud SQL connections:

    • Check VPC connector is attached
    • Verify Cloud SQL instances are running
    • Check IAM permissions

  3. Verify environment variables:

    • Check Doppler secrets are set correctly
    • Verify connection strings are valid

Metabase Won't Start​

  1. Check logs (see above)

  2. Verify database connection:

    • Check METABASE_DB_CONNECTION_URI is correct
    • Verify password is URL-encoded if needed
    • Test connection manually

  3. Check resource allocation:

    • Verify memory (2Gi) and CPU (2) are sufficient
    • Check Cloud Run metrics for resource usage

Database Connection Fails in Metabase UI​

  1. Verify Cloud SQL instance is accessible:

    gcloud sql instances describe flowpos-db \
      --project=barto-dev

  2. Check connection string format:

    • Unix socket path: /cloudsql/PROJECT:REGION:INSTANCE
    • Password URL-encoded if contains special characters

  3. Test connection from Cloud Run:

    • Use Cloud Run exec to test connection
    • Or check Cloud SQL logs

Next Steps​

After successful deployment:

  1. ✅ Update implementation plan (mark Phase 4 as complete)
  2. ➡️ Proceed to Phase 5: Dashboard Creation & Configuration
  3. ➡️ Proceed to Phase 6: Security Hardening

Quick Reference Commands​

# Get service URL
gcloud run services describe flowpos-metabase-<env> \
  --region=us-central1 \
  --project=<project-id> \
  --format="value(status.url)"

# Check service status
gcloud run services describe flowpos-metabase-<env> \
  --region=us-central1 \
  --project=<project-id>

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

# Test health endpoint
curl https://<metabase-url>/api/health