Skip to main content

Evolution API on Cloud Run — Lab Guide

📖 Configuration Guide

Overview​

Estimated time: 45–90 minutes

Evolution API is an open-source Node.js WhatsApp Business API gateway (built on the Baileys library) that provisions WhatsApp instances, sends and receives messages, and exposes a REST API plus a manager UI for wiring WhatsApp into other systems. This lab takes you through the full operational lifecycle of the Evolution API on Cloud Run module on Google Cloud: deploy it, access and verify it, run it day-to-day, observe it, diagnose common problems, and tear it down.

The lab focuses on operating the Cloud Run module and the Google Cloud platform, not on Evolution API / WhatsApp product features. For the complete list of provisioned services and every configuration input (organised by group), see the Configuration Guide — this lab deliberately does not duplicate that detail so it stays accurate over time.

Objectives​

By the end of this lab you will be able to:

  • Deploy the module from the RAD platform and locate the resources it provisions.
  • Access and verify the running service, and complete first-run WhatsApp setup.
  • Perform day-2 operations — inspect, update, and manage secrets, cache, and backups.
  • Observe the service with Cloud Logging and Cloud Monitoring.
  • Diagnose and resolve the most common deployment and runtime issues.
  • Tear the deployment down cleanly.

Prerequisites​

  • Services_GCP (provides the VPC, Cloud SQL, Filestore NFS, Artifact Registry, and shared service accounts this module depends on). You do not need to deploy this yourself first — the platform automatically detects whether it already exists in the target project and provisions it before this module if not (see Task 1).
  • A Google Cloud project with billing enabled.
  • gcloud CLI authenticated: gcloud auth login and gcloud auth application-default login.
  • Project Owner (or equivalent) IAM on the project.
  • Bringing your own project? Before the first deploy into it, the deployment confirmation dialog asks you to prove you control it (Get verification code, run the commands it shows as a project Owner, then Verify) and to give the RAD deployment service account the Owner role. A project RAD creates for you needs neither.
  • Advanced mode for later changes. The create form asks only for the first page of inputs (and, in a project RAD creates for you, little more than the tenant name and region). Every other input in the Configuration Guide — including the scaling and version inputs in the Day-2 tasks — is changed afterwards with Update on the deployment's page after ticking Enable advanced mode, which needs a credit balance that covers the update's estimated build cost (updates never carry a module fee). On a lab environment only an administrator can use Advanced mode.
  • RAD platform access with permission to deploy modules into the project.

Set these shell variables once; every task below reuses them:

export PROJECT="<your-gcp-project-id>"
export REGION="us-central1"          # the region you deploy into

Task 1 — Deploy the module [Automated]​

  1. In the RAD platform, open Solutions → Solution Catalog → RAD modules, then open Evolution API (Cloud Run) from the Platform Modules list, choose Configuration Form under How would you like to configure this deployment? (the form opens on the Conversational Assistant if you hold purchased credits or are a partner or administrator), set project_id, and review the inputs. Configure only what you need — the Configuration Guide documents every input by group, with defaults. Click Deploy Module, review the estimated cost in the Deployment Confirmation dialog when it appears and click Submit (if the dialog then adds a confirmation step, such as verifying a project you bring, complete it and click Confirm), which opens the deployment status page with real-time logs.

  2. The platform provisions the Cloud Run service (pinned to a single always-warm instance), a Cloud SQL (PostgreSQL 15) database with its Secret Manager secrets (the auto-generated AUTHENTICATION_API_KEY admin key and the database password), a Cloud Storage data bucket, a Filestore NFS instance (which also hosts the default Redis endpoint), builds the container image, and runs a one-shot database initialisation job. First deploys take roughly 20–35 minutes (Cloud SQL and NFS creation dominate).

  3. When it completes, discover the resources with name-agnostic filters (so the commands keep working regardless of the deployment suffix):

    SERVICE=$(gcloud run services list --project="$PROJECT" --region="$REGION" \
      --filter="metadata.name~evolutionapi" --format="value(metadata.name)" --limit=1)
    SERVICE_URL=$(gcloud run services describe "$SERVICE" \
      --project="$PROJECT" --region="$REGION" --format="value(status.url)")
    echo "Service: $SERVICE"
    echo "URL:     $SERVICE_URL"

Task 2 — Access & verify [Manual]​

  1. Confirm the service is healthy. Evolution API's startup and liveness probes target the root / — an unauthenticated status endpoint that responds once the server is up (allow up to ~7 minutes on first boot while Prisma migrations run):

    curl -s "$SERVICE_URL/"   # expect a JSON status payload, not a connection error

  2. Retrieve the auto-generated global admin key from Secret Manager:

    API_KEY_SECRET=$(gcloud secrets list --project="$PROJECT" \
      --filter="name~api-key" --format="value(name)" --limit=1)
    API_KEY=$(gcloud secrets versions access latest --secret="$API_KEY_SECRET" --project="$PROJECT")
    echo "$API_KEY"

  3. Open $SERVICE_URL/manager in a browser (or call the REST API directly) using $API_KEY as the apikey header, and create your first WhatsApp instance:

    curl -s -X POST "$SERVICE_URL/instance/create" \
      -H "apikey: $API_KEY" -H "Content-Type: application/json" \
      -d '{"instanceName":"lab-instance","qrcode":true,"integration":"WHATSAPP-BAILEYS"}'

  4. Fetch the connection QR code and scan it from WhatsApp on your phone (Linked Devices → Link a Device) to connect the number:

    curl -s "$SERVICE_URL/instance/connect/lab-instance" -H "apikey: $API_KEY"

    Never rotate AUTHENTICATION_API_KEY after this point — rotating it makes every already-provisioned WhatsApp instance unreachable and returns 401 to every client still holding the old key.

Task 3 — Operate & keep it running (Day-2) [Manual]​

  1. Inspect the service and its revisions (each deploy creates an immutable revision; traffic shifts to the newest healthy one):

    gcloud run services describe "$SERVICE" --project="$PROJECT" --region="$REGION"
    gcloud run revisions list --service="$SERVICE" --project="$PROJECT" --region="$REGION"

  2. Do not scale beyond one instance. WhatsApp (Baileys) socket sessions are held in the instance's memory and are not shared across replicas — min_instance_count and max_instance_count are pinned to 1 by design. Raising max_instance_count fragments live connections and duplicates webhook deliveries; leave it alone.

  3. Update the application version by changing the version input (default v2.1.1) in the RAD platform and applying it via Update — a new image builds and Prisma migrations run again on the next boot.

  4. Manage secrets, cache, and jobs:

    gcloud secrets list --project="$PROJECT" --filter="name~evolutionapi"
    gcloud run jobs list --project="$PROJECT" --region="$REGION"          # db-init + any scheduled jobs
    # Confirm the Redis cache URI resolved in the running revision:
    gcloud run services describe "$SERVICE" --project="$PROJECT" --region="$REGION" \
      --format='value(spec.template.spec.containers[0].env)' | tr ';' '\n' | grep -i redis

  5. Open a database session for inspection or maintenance:

    INSTANCE=$(gcloud sql instances list --project="$PROJECT" --format="value(name)" --limit=1)
    # Role and database are tenant-prefixed (e.g. evolutionapidemo426161cf) — not the bare app name.
    DB_USER=$(gcloud sql users list --instance="$INSTANCE" --project="$PROJECT" \
      --format="value(name)" --filter="name~^evolutionapi" --limit=1)
    DB_NAME=$(gcloud sql databases list --instance="$INSTANCE" --project="$PROJECT" \
      --format="value(name)" --filter="name~^evolutionapi" --limit=1)
    gcloud sql connect "$INSTANCE" --user="$DB_USER" --database="$DB_NAME" --project="$PROJECT"

Task 4 — Observe: Logging & Monitoring [Manual]​

  1. Logs — from the CLI or the Logs Explorer. The entrypoint emits [cloud-entrypoint] markers that confirm the resolved DB/Redis/URL config on boot:

    gcloud run services logs read "$SERVICE" --project="$PROJECT" --region="$REGION" --limit=50

    Logs Explorer filter: resource.type="cloud_run_revision" AND resource.labels.service_name="<service>".

  2. Monitoring — open the Cloud Run dashboard for the service and review request count, request latency (P50/P95/P99), and CPU / memory utilisation (the instance stays warm at min=1, so expect a small steady baseline rather than scale-to-zero behaviour). The module also provisions an uptime check; confirm it is green under Monitoring → Uptime checks, and review Alerting → Policies.

Task 5 — Troubleshoot & debug [Manual]​

Durable techniques for the failure modes you are most likely to hit. These are platform-level diagnostics and do not change with Evolution API releases.

  • Revision unhealthy / service won't serve: inspect the latest revision and its logs for startup errors, and confirm env vars and secrets resolved. The startup probe targets / and allows up to ~7 minutes on first boot (60s initial delay plus a 30-retry window while Prisma migrates). 
    gcloud run revisions list --service="$SERVICE" --project="$PROJECT" --region="$REGION"
    gcloud run services logs read "$SERVICE" --project="$PROJECT" --region="$REGION" --limit=100
  • Database connection errors: confirm the Cloud SQL instance is RUNNABLE, the DB password secret exists, and the initialisation job completed successfully.
  • Initialisation job failed: list executions and read the failed one's logs: 
    gcloud run jobs executions list --job="${SERVICE}-db-init" \
      --project="$PROJECT" --region="$REGION"
  • Redis cache silently disabled: if enable_redis=true but the cache URI env var is blank, check that either enable_nfs=true (so the NFS server IP is used) or an explicit redis_host is set.
  • 401 on every WhatsApp API call: the apikey header is missing/wrong, or AUTHENTICATION_API_KEY was rotated after instances were already provisioned — the fix is to re-provision the affected WhatsApp instances, not to rotate back.
  • Image build failed: review Cloud Build history for the failed build's log.
  • 403 / permission errors: verify the runtime service account's IAM roles.

See the Configuration Guide's Configuration Pitfalls & Sensible Defaults section for setting-specific gotchas (including the critical rule never to rotate AUTHENTICATION_API_KEY or raise max_instance_count after first boot).

Task 6 — Tear down [Automated]​

On the Deployments page, open the deployment and click the Trash icon (Delete). Delete runs terraform destroy and is irreversible (the deployment record is retained for history). If a deployment is stuck and the RAD platform can no longer manage it (for example after manual changes that conflict with the Terraform state), use Purge instead (from the same Delete dialog) — it removes the deployment from RAD's records without destroying the cloud resources (it makes RAD forget the deployment). This removes everything the module created — the Cloud Run service, Cloud SQL database, Secret Manager secrets, GCS buckets, and Artifact Registry images. Resources owned by Services_GCP (the VPC, shared Cloud SQL, NFS, registry) are managed separately and are not removed here.

Summary​

TaskTypeOutcome
1 — DeployAutomatedModule provisions Cloud Run (pinned single instance), Cloud SQL (PostgreSQL 15), NFS/Redis, secrets, storage bucket, and runs DB init
2 — Access & verifyManualHealth check passes; retrieve the admin API key; create and connect a WhatsApp instance via QR code
3 — OperateManualInspect revisions, update version, manage secrets/cache/jobs, DB access — do not scale beyond one instance
4 — ObserveManualQuery Cloud Logging; review Cloud Monitoring metrics and uptime check
5 — TroubleshootManualDiagnose revision, database, init-job, Redis, auth-key, build, and IAM issues
6 — Tear downAutomatedDelete (Trash) removes all module resources

Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.

By · Google Cloud certified: ACE · PCA · PCD · PDE · PSE · CDL

Last updated on