drive-apig
v2.4.2

Local setup

1. Clone and install

bash
git clone git@github.com:caradvice/drive-apig.git
cd drive-apig

export GH_REGISTRY_TOKEN="ghp_..."   # read:packages scope
export SERVERLESS_ACCESS_KEY="..."    # from serverless.com

corepack enable   # volta manages node/yarn versions automatically
yarn install

Yarn 4 workspaces hoist dependencies to the repo root (single node_modules).

2. Configure AWS profiles

bash
# ~/.aws/config or credentials
[profile aws-drive-staging-admin]
# ... sufficient for dev + staging
[profile aws-drive-prod-admin]
# ... required for prod deploys only

Do not change profile names — serverless.common.yml + the g:* scripts reference them directly.

3. Generate .env.local for a service

Each service needs a .env.local file with actual SSM parameter values for offline use:

bash
yarn gen-env leads                          # default: staging profile, dev stage
yarn gen-env leads --stage staging          # stage-specific params
yarn gen-env leads --profile aws-drive-prod-admin

What gen-env does:

  1. Reads the service's serverless.yml
  2. Extracts all ssm:/... references from function environment variables
  3. Fetches actual values from AWS Parameter Store
  4. Writes .env.local into the service directory (gitignored — never commit)

Failed parameters are commented out in the generated file.

4. Run a service offline

From inside a service folder:

bash
cd services/leads
yarn offline

yarn offline runs the root g:offline workspace script, which:

  1. Starts Docker Compose (docker compose up -d) — brings up:
    • SQS (elasticmq) on ports 9324 (queue) / 9325 (management)
    • DynamoDB Local on port 8000
  2. Loads .env.local via DOTENV_CONFIG_PATH=.env.local + -r dotenv/config
  3. Creates resources — queues and tables declared in the service's serverless.yml are provisioned locally
  4. Seeds DynamoDB — seed data from data/seed/*.json is loaded (configured in serverless.yml custom.serverless-dynamodb.seed)
  5. Starts serverless-offline with --reloadHandler --noAuth --verbose — API served at http://localhost:3000 (no API key checks)

The full env includes: IS_LOCAL=1, NODE_ENV=development, source maps, AWS_XRAY_context_missing=LOG_ERROR.

DLQs are excluded in local mode via serverless-if-else (offline doesn't work with DLQs).

Overriding defaults

All g:* scripts resolve the AWS profile and region from env vars with sensible defaults:

VariableDefaultUsed for
AWS_PROFILE_NAMEaws-drive-staging-admin (dev/staging), aws-drive-prod-admin (prod)AWS auth
SLS_REGIONap-southeast-2deploy region
APIG_SERVE_HOSTNAMElocalhost:3000offline API hostname

Override by exporting before the command:

bash
AWS_PROFILE_NAME=my-custom-profile yarn offline
SLS_REGION=us-east-1 yarn deploy

Per-service commands

Run from inside a service folder (e.g. services/leads/). Each service package.json defines clean aliases that delegate to the root g:* workspace scripts:

CommandAction
yarn offlineRun offline (Docker DynamoDB/SQS + serverless-offline)
yarn testUnit tests
yarn test:watchUnit tests (watch mode)
yarn deployDeploy to dev (alias: yarn deploy:dev)
yarn deploy:stagingDeploy to staging
yarn deploy:prodDeploy to prod (prod profile)
yarn infoStack info
yarn packagePackage CFN (no deploy)
yarn pruneClean old deployments
yarn removeRemove the stack

Docs site (separate package)

bash
cd docs/site
GH_REGISTRY_TOKEN="${GH_REGISTRY_TOKEN:-dummy}" yarn install
yarn dev    # http://localhost:3210

See Cloudflare Pages for hosting.

Troubleshooting

  • Environment variable not found (GH_REGISTRY_TOKEN) — export before yarn install/yarn <script>. The root .yarnrc.yml requires it for the @caradvice scope.
  • DynamoDB/SQS not starting — ensure Docker is running. docker compose up -d is called automatically by yarn offline.
  • DLQ errors offline — expected; DLQs are excluded in local mode. If a service declares a DLQ, it's skipped via serverless-if-else.
  • Wrong Node/Yarn version — ensure Volta is installed (volta -v). It pins versions automatically.
Esc
Esc Close