Documentation/Deployment/Deploy to AWS / GCP — Verification Runbook

Deploy to AWS / GCP — Verification Runbook

A hands-on runbook: build an app in App Studio, hit Go Live, ship its UI to your own AWS or GCP account with one command, and verify the deploy actually works. Your data stays in Supero.

What You'll Do

Build the app in App Studio, click Go Live, and ship the app's UI into your own cloud. Only the UI container runs in your AWS or GCP account — the app's data, auth, and AI stay in Supero. Follow the lane for your cloud and tick every check.

•App UI runs on your cloud; your data stays in Supero.
•Connect once, per project — later deploys reuse it.
•Requires the supero SDK, version 3.5.954 or later.

Before You Start

•A paid plan with live-hosting. Cloud deploy is entitlement-gated — without it the wizard shows "Upgrade required (402)".
•Cloud admin access. Connecting runs one-time in your own AWS or GCP account, so you need admin there (IAM user creation / project owner).
•GCP only: billing enabled. The connect step enables the Cloud Run, Cloud Build, and Artifact Registry APIs — billing must be on first.
•The supero CLI: pip install --upgrade supero (version 3.5.954+). Your cloud's Cloud Shell already has the rest of the tooling.

Steps 1–2 — The Same for Both Clouds

1. Build the app in App Studio

Describe the app, then click Generate. The in-app preview opens in about 5 minutes and seeds sample data — a deploy ships whatever data the project currently has, so let the preview seed it at least once.

2. Open Go Live and pick a cloud

From the generated app, click Go Live, then choose Deploy to AWS or Deploy to Google Cloud. Continue in the matching lane below.

AWS — ECS Express (Fargate)

Roughly 3–6 minutes end to end.

1. Connect once (skip if status is already active)

In AWS CloudShell — signed in to the target account as an admin — run the SDK connect. It launches a CloudFormation stack (a scoped IAM user plus an ECR repo, an S3 deploy bucket, a CodeBuild project, and the ECS task-execution and infrastructure roles) and prints the Outputs. There is no S3 bucket to pre-create.

bash

pip install supero && supero connect-aws --region us-east-1

Prefer the console? Launch the CloudFormation template from the wizard's Setup guide tab and tick the acknowledgement for named IAM resources (CAPABILITY_NAMED_IAM).

2. Paste the Outputs into the wizard

•AwsAccessKeyId
•AwsSecretAccessKey
•DeployBucket
•EcrRepoUri
•CodeBuildProjectName
•EcsTaskExecutionRoleArn
•EcsInfrastructureRoleArn

3. Launch

Click deploy. Status moves building → deploying → running.

💡 Expected result

Running, with a live URL like https://su-<id>.ecs.us-east-1.on.aws.

GCP — Cloud Run

Roughly 3–6 minutes end to end.

1. Connect once (skip if status is already active)

In Google Cloud Shell, run the SDK connect with the External ID the wizard shows. It enables the required APIs, provisions the deploy service account, runtime service account, Artifact Registry repo, and source bucket, wires the impersonation trust edge, grants the deploy SA run.viewer, and prints the Outputs. No service-account key ever leaves your project, and the connect is idempotent — safe to re-run.

bash

pip install supero && supero connect-gcp \
  --project-id <your-project> \
  --external-id <from the wizard> \
  --region us-central1

2. Paste the Outputs into the wizard

•gcp_project_id
•deploy_sa_email
•artifact_registry_repo
•cloud_run_service_account
•source_bucket

3. Launch

Click deploy. Status moves building → deploying → running.

💡 Expected result

Running, with a Cloud Run URL like https://<service>-<hash>-uc.a.run.app. This needs supero 3.5.954 or later so the deploy SA is granted run.viewer (see troubleshooting).

Verify It Worked — Tick Each

⚠️ A green status is not the same as a working app

A deploy can report "running" while serving a blank shell or an empty catalog. Walk this checklist once per target before you call the deploy done.

•The wizard shows Connected / config status active for your cloud.
•The deploy reaches running and shows a live URL.
•Opening the URL loads the app home / storefront — HTTP 200, not a blank page.
•Real data appears — products or records show, not an empty shell.
•No red "Couldn't reach the server" banner — this confirms the scoped API key was injected.
•The first hit may be slow, then fast — Cloud Run / ECS scaled to zero; wait a few seconds and retry.

bash

curl -s -o /dev/null -w "GET / -> %{http_code}\n" "https://YOUR-DEPLOY-URL/"

If Something Fails

What you see	Fix
"Upgrade required (402)" at deploy	The plan lacks live-hosting. Upgrade to a paid plan with the live-hosting (servers) entitlement.
GCP: 502 at the status step, or "run.services.get denied"	The deploy SA is missing run.viewer (created by a connect from an older SDK). Re-run supero connect-gcp on 3.5.954+ — it is idempotent and adds the grant — or grant run.viewer to the deploy SA once as a project admin.
GCP: supero connect-gcp errors partway through service-account setup	An older SDK build. Upgrade with pip install --upgrade supero (3.5.954+) and re-run — the connect is idempotent.
App loads but is empty	The project has no data yet. Open a Supero preview once (it seeds), then redeploy.
AWS stack won't create	Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names" — the stack creates named IAM resources (CAPABILITY_NAMED_IAM).
Deploy hangs, or a stray service is left running	Use Remove deployment in the dialog to tear it down, then redeploy. Deterministic service names make re-deploys safe.

Next Steps

•Deploy to Your Own AWS or GCP — the full guide, with the exact IAM permissions, cost, logs, and teardown detail behind this runbook.
•Choosing a Deployment Option — the decision matrix across Supero Cloud, your own AWS or GCP, and self-hosting the whole platform.
•Publish Your App (Go Live / Supero Cloud) — the one-click hosted alternative to bringing your own cloud.

← PreviousDeploy to Your Own AWS or GCP Next →On-Premise Deployment

On this page