Skip to content

README.md

Latest commit

 

History

History
140 lines (106 loc) · 5.16 KB

README.md

File metadata and controls

140 lines (106 loc) · 5.16 KB

TotemBound DevOps

GitHub Actions workflows for building and deploying the TotemBound game.

Workflows

App (Frontend → S3 + CloudFront)

Workflow File What it does
CI app build ci-app-build.yml Checkout → lint → test → Vite build → zip → S3
CI app deploy ci-app-deploy.yml Download zip from S3 → sync to app bucket → invalidate CloudFront
PROD app build prod-app-build.yml Same as CI, prod env vars + PostHog key
PROD app deploy prod-app-deploy.yml Same as CI, prod S3 bucket + CloudFront distribution

API (Lambda)

Workflow File What it does
CI API build ci-api-build.yml Checkout → npm ci → lint → test → build → package zip → S3
CI API deploy ci-api-deploy.yml lambda update-function-code from S3 zip → wait → verify
PROD API build prod-api-build.yml Same as CI, prod credentials
PROD API deploy prod-api-deploy.yml Same as CI, prod Lambda function

Infrastructure (CloudFormation)

Workflow File What it does
CI infra deploy ci-infra-deploy.yml Upload CF template to S3 → create/update stack → print outputs
PROD infra deploy prod-infra-deploy.yml Same as CI, prod credentials + region

Stacks (deploy order matters — cross-stack references):

  1. core — 9 DynamoDB tables + IAM execution role
  2. cognito — User Pool + App Client (token validity, auth flows)
  3. api — Lambda function + REST API Gateway + Cognito Authorizer
  4. iot — Cognito Identity Pool + IoT policies for real-time push via MQTT/WebSocket

When deploying all, stacks run sequentially: core → cognito → api → iot.

Environments

Staging Production
Region us-west-2 us-east-1
AWS credentials AWS_ACCESS_KEY_ID2 AWS_ACCESS_KEY_ID
S3 releases bucket totemboundci-releases totembound-releases
S3 app bucket totemboundci-app totembound-app
CloudFront (app) E30D3Q6UOWWMO4 E3TBCP5P18U4EE
Lambda function totemboundci-api totembound-api
Stack prefix totemboundci-*-stack totembound-*-stack
Frontend URL totembound-test.net totembound.com

S3 Release Bucket Layout

totemboundci-releases/
  totem-app/
    release-{version}.zip            # Frontend build
  totem-api/
    totembound-api-{version}.zip     # Lambda code package
    totembound-api-latest.zip
    cloudformation/
      core-{version}.yml             # CF templates (versioned + latest)
      core-latest.yml
      cognito-{version}.yml
      cognito-latest.yml
      api-{version}.yml
      api-latest.yml
      iot-{version}.yml
      iot-latest.yml

Deploy Pattern

All deployments follow the same flow: build → version → S3 → deploy from S3.

App:    source → lint/test → vite build → zip → S3 → unzip → sync to app bucket → CloudFront invalidation
API:    source → lint/test → build → package zip → S3 → lambda update-function-code from S3
Infra:  source → upload template to S3 → cloudformation create/update-stack from local file → wait

Triggers

All workflows use workflow_dispatch (manual trigger from GitHub Actions UI).

Build workflows accept:

  • build_version — version string (e.g. 0.2.0)
  • source_branch — git branch to build from (default: main)

Deploy workflows accept:

  • release_version — must match a version already in S3

Infra deploy accepts:

  • stack — which stack to deploy (core, cognito, api, or all)
  • release_version — version tag for the template in S3
  • source_branch — branch containing CF templates (default: main)

Local Deploy (CLI)

Infrastructure can also be deployed from a local machine using Node.js scripts in totem-api/scripts/:

cd totem-api
node scripts/deploy-core.js      # Deploy core stack
node scripts/deploy-cognito.js   # Deploy cognito stack
node scripts/deploy-api.js       # Deploy api stack (also packages + uploads Lambda zip)

Or directly with AWS CLI:

aws cloudformation update-stack \
  --stack-name totemboundci-cognito-stack \
  --template-body file://infrastructure/cloudformation/cognito.yml \
  --parameters ParameterKey=Environment,ParameterValue=staging \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-west-2

Parameter Files

CloudFormation parameters live in totem-api/infrastructure/:

File Used by
params-core-staging.json core stack (staging)
params-cognito-staging.json cognito stack (staging)
params-api-staging.json api stack (staging) — Stripe price IDs, SSM paths

Prod parameter files (params-*-prod.json) will be added when production infrastructure is deployed.

Secrets (GitHub)

Secret Purpose
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY Prod AWS credentials
AWS_ACCESS_KEY_ID2 / AWS_SECRET_ACCESS_KEY2 Staging AWS credentials
PAT GitHub Personal Access Token for cross-repo checkout