API Staging Runbook
The Phenom API staging environment, backing the Dev NEST deployment and used for pre-production integration testing.
Source:
asset-registry.yaml; curl https://api-staging.thephenom.app → HTTP 500; staging topology mirrors prod but not confirmed independently
C2PA signed · SanMarcSoft AI content credential
What it is
api-staging.thephenom.app is the staging version of the Phenom API, backing the Dev NEST environment at dev-nest.thephenom.app. It runs the same Hasura GraphQL and Auth service stack as production but against the dev database (phenom-dev-postgres). Engineers validate schema migrations, new API features, and integration changes here before promoting to the production API.
Deployment chain
| Layer | Value |
|---|---|
| URL | https://api-staging.thephenom.app |
| DNS | Cloudflare (proxied, orange-cloud) |
| Hosting | AWS App Runner or ALB+ECS (staging instance) |
| Services | Hasura GraphQL engine + Auth service (staging config) |
| Region | us-east-1 |
| AWS profile | phenom |
| Database | phenom-dev-postgres (RDS PostgreSQL, us-east-1) |
| Auth | AWS Cognito pool us-east-1_knEL7cqS3 (shared with prod) |
Common operations
Check staging API health
curl -sf https://api-staging.thephenom.app/healthz
# Expected: "OK" or JSON {"status":"OK"}
Restart staging service (App Runner)
SERVICE_ARN=$(aws apprunner list-services \
--profile phenom --region us-east-1 \
--query 'ServiceSummaryList[?contains(ServiceName,`api-staging`)].ServiceArn' \
--output text)
aws apprunner start-deployment \
--service-arn "$SERVICE_ARN" \
--profile phenom \
--region us-east-1
Restart staging service (ECS Fargate)
aws ecs update-service \
--cluster phenom-dev-cluster \
--service phenom-api-staging \
--force-new-deployment \
--profile phenom \
--region us-east-1
Apply Hasura migrations to staging
cd hasura/
# Apply to staging first, verify, then apply to prod
hasura migrate apply \
--endpoint https://api-staging.thephenom.app \
--admin-secret "$HASURA_ADMIN_SECRET_STAGING" \
--database-name default
hasura metadata apply \
--endpoint https://api-staging.thephenom.app \
--admin-secret "$HASURA_ADMIN_SECRET_STAGING"
Run a test GraphQL query against staging
curl -sf -X POST https://api-staging.thephenom.app/v1/graphql \
-H "Content-Type: application/json" \
-d '{"query":"{ __typename }"}' | python3 -m json.tool
# Expected: {"data":{"__typename":"query_root"}}
View staging logs
# App Runner:
aws logs tail /aws/apprunner/phenom-api-staging \
--follow \
--profile phenom \
--region us-east-1
# ECS:
aws logs tail /ecs/phenom-api-staging \
--follow \
--profile phenom \
--region us-east-1
Verify it is working
curl -si https://api-staging.thephenom.app/healthz
# Expected: HTTP/2 200
curl -sf -X POST https://api-staging.thephenom.app/v1/graphql \
-H "Content-Type: application/json" \
-d '{"query":"{ __typename }"}' | grep '__typename'
# Expected: line containing "__typename" confirming GraphQL engine is live
Common failure modes
| Symptom | Likely cause | Remediation |
|---|---|---|
| 502 / 503 | Staging service crashed | Check CloudWatch logs; restart App Runner or ECS service |
| Migration errors in staging | Schema conflict or bad migration file | Roll back migration; fix SQL; re-apply |
| Dev NEST can’t reach staging API | CORS misconfiguration or env var wrong | Check NEXT_PUBLIC_API_URL in CF Pages dev environment settings |
| Staging diverged from prod | Metadata or migrations applied only to one env | Apply pending migrations to staging first, then prod |
| RDS dev connection errors | phenom-dev-postgres unreachable |
See RDS dev runbook |
Related
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.