03.01.API Setup

03.01. API Setup

Prerequisites

Python 3.10+
Docker and Docker Compose
GCP service account keys (for deployment)
Git access to all bnc-cpt-* repositories

Local Development Setup

1. Clone Repositories

mkdir -p /opt/bnc/bnc-cpt && cd /opt/bnc/bnc-cpt
for repo in bnc-cpt-api bnc-cpt-wui bnc-cpt-utl bnc-cpt-inf bnc-cpt-cnf tpl-gen; do
  git clone git@github.com:csitea/$repo.git
done

2. Python Virtual Environment

cd /opt/bnc/bnc-cpt/bnc-cpt-api/src/python/cpt-api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Environment Variables

Copy the example environment file and configure:

cp .env.example .env

Required variables:

Variable	Description	Example
STRIPE_SECRET_KEY	Stripe API key	`sk_test_...`
STRIPE_WEBHOOK_SECRET	Stripe webhook signing secret	`whsec_...`
PAYPAL_CLIENT_ID	PayPal client ID	`AW...`
PAYPAL_CLIENT_SECRET	PayPal client secret	`EK...`
JWT_SECRET_KEY	JWT signing key (min 32 chars)	`your-secret-key-min-32-characters`
ADMIN_USERNAME	Admin login username	`admin`
ADMIN_PASSWORD	Admin login password (plaintext for local)	`your-password`

4. Run Locally

python run.py
# API runs on http://localhost:8100
# Swagger UI: http://localhost:8100/docs

5. Docker-Based Setup (Alternative)

From the UTL module:

cd /opt/bnc/bnc-cpt/bnc-cpt-utl
export UID=$(id -u) GID=$(id -g)
make do-setup-api

This builds the API Docker container and starts it on port 8100.

GCP Service Account Keys

For deployment and GCP operations, place service account keys at:

~/.gcp/.bnc/
├── key-bnc-cpt-inf.json
├── key-bnc-cpt-dev.json
├── key-bnc-cpt-tst.json
├── key-bnc-cpt-prd.json
└── key-bnc-cpt-all.json

Keys are created during GCP project setup (see bnc-cpt-inf/doc/bnc-cpt.ISG.md).

CI/CD Setup

GitHub Repository Variables

Set these in the GitHub repository settings (Settings > Secrets and variables > Actions > Variables):

Variable	Value
ORG	`bnc`
APP	`cpt`
PROJ	`bnc-cpt-api`
GH_ORG	`csitea`

GitHub Repository Secrets

Set these in Settings > Secrets and variables > Actions > Secrets:

Secret	Description
ALL_CSI_GITHUB_TOKEN	Personal access token for cloning team repos
GCP_SA_KEY_INF	Content of `key-bnc-cpt-inf.json`
GCP_SA_KEY_DEV	Content of `key-bnc-cpt-dev.json`
GCP_SA_KEY_TST	Content of `key-bnc-cpt-tst.json`
GCP_SA_KEY_PRD	Content of `key-bnc-cpt-prd.json`

These secrets are provisioned automatically via Terraform step 120-github-general-secrets.

CI Workflow (`ci.yaml`)

Trigger: Push to any branch, or manual workflow_dispatch
What it does: Clones all repos, builds API Docker container, runs pytest
Purpose: Quality gate before merging to master

Unified Workflow (`ci.yaml`)

Trigger: Push to master (path src/python/cpt-api/**), or manual workflow_dispatch
Auto-deploy: inf + dev on master push
Manual deploy: tst, prd via workflow_dispatch only
What it does: Build Docker image, push to Artifact Registry, deploy to Cloud Run, map custom domain, health check
Post-deploy tests: After deploy, runs smoke tests (health, docs, payment endpoint) against the deployed API URL. Fetches test credentials from GCP Secret Manager. Skips prd environment.

GitHub Team Requirement

The CI/CD cloning step uses gh api orgs/{GH_ORG}/teams/team-{ORG}-{APP}-int/repos to discover all repos. Ensure:

A team named team-bnc-cpt-int exists in the GitHub org
All bnc-cpt-* repos are added to this team
The ALL_CSI_GITHUB_TOKEN has read:org and repo scopes

GCP Infrastructure Prerequisites

Before the API can be deployed, these Terraform steps must be provisioned (from bnc-cpt-utl/):

cd /opt/bnc/bnc-cpt/bnc-cpt-utl

# 1. Enable GCP APIs
make do-generate-config-for-step ENV=dev STEP=001-enable-gcp-services
make do-provision ENV=dev STEP=001-enable-gcp-services

# 2. Create Artifact Registry (Docker image repository)
make do-generate-config-for-step ENV=dev STEP=025-gcp-artifact-registry
make do-provision ENV=dev STEP=025-gcp-artifact-registry

# 3. Create GCP Secret containers
make do-generate-config-for-step ENV=dev STEP=029-create-gcp-secrets
make do-provision ENV=dev STEP=029-create-gcp-secrets

# 4. Populate secret values
make do-gcp-sync-secrets ENV=dev

# 5. Deploy Cloud Run (optional - CD workflow handles this)
make do-generate-config-for-step ENV=dev STEP=030-gcp-cloud-run
make do-provision ENV=dev STEP=030-gcp-cloud-run

Domain Setup

Custom domains ({env}.api.carpulsetracker.com) require one-time verification:

Verify carpulsetracker.com in Google Search Console
Add DNS TXT record for verification
Create domain mappings in GCP Console

See bnc-cpt-inf/doc/bnc-cpt.ISG.md for detailed domain verification steps.

Verification

After setup, verify the API is running:

# Local
curl http://localhost:8100/health | jq '.'

# Deployed
curl https://dev.api.carpulsetracker.com/health | jq '.'
curl https://dev.api.carpulsetracker.com/docs  # Swagger UI in browser