06-Operations / 06.04.Utilities-Operations

06.04.Utilities Operations

06.04. Utilities Operations

This guide provides operational procedures for common tasks using the UTL orchestration module.

Working Directory

All commands run from:

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

Docker Container Management

Start Containers

# Start all containers
make do-setup-bnc-cpt-all

# Start individual containers
make do-setup-api              # API backend (port 8100)
make do-setup-wui              # WUI frontend (port 3333)
make do-setup-tf-runner        # Terraform runner
make do-setup-app-inf          # All infrastructure containers

Rebuild Without Cache

make do-setup-api-no-cache     # Rebuild API container
make do-setup-wui-no-cache     # Rebuild WUI container

Check Running Containers

docker ps | grep bnc-cpt

Expected containers: - con-bnc-cpt-api (port 8100) - con-bnc-cpt-wui (port 3333) - con-bnc-cpt-the-bot - con-bnc-cpt-gateway (port 80) - con-bnc-cpt-redis (port 6379) - con-bnc-cpt-tf-runner - con-bnc-cpt-tpl-gen - con-bnc-cpt-conf-validator

Clean Up Docker

make do-prune-docker-system

Version Management

Bump WUI Version

# Patch bump (default): v1.0.1 -> v1.0.2
./run -a do_version_bump

# Minor bump: v1.0.9 -> v1.1.0
BUMP=minor ./run -a do_version_bump

# Major bump: v1.9.9 -> v2.0.0
BUMP=major ./run -a do_version_bump

# Push the tag
git -C /opt/bnc/bnc-cpt/bnc-cpt-wui push origin <tag>

Bump API Version

TARGET_PROJ=/opt/bnc/bnc-cpt/bnc-cpt-api ./run -a do_version_bump

# Push the tag
git -C /opt/bnc/bnc-cpt/bnc-cpt-api push origin <tag>

Check Current Versions

# WUI version
git -C /opt/bnc/bnc-cpt/bnc-cpt-wui describe --tags --abbrev=0

# API version
git -C /opt/bnc/bnc-cpt/bnc-cpt-api describe --tags --abbrev=0

Deploying WUI (Frontend)

Via Shell Action

# Single environment
ENV=dev ./run -a do_gcp_deploy_wui

# All environments
for env in inf dev tst prd; do
  ENV=$env ./run -a do_gcp_deploy_wui
done

Via GitHub Actions

gh workflow run ci.yaml -f environment=dev --repo csitea/bnc-cpt-wui

Deploying API (Backend)

Via Shell Action

# Full deploy (build + push + deploy)
ENV=dev ./run -a do_gcp_deploy_api_full

# Just deploy existing image
ENV=dev ./run -a do_gcp_deploy_cloud_run

Via GitHub Actions

gh workflow run cd.yaml -f environment=dev --repo csitea/bnc-cpt-api

Terraform Operations

Generate Config

make do-generate-config-for-step ENV=dev STEP=029-create-gcp-secrets

Provision (Apply)

make do-provision ENV=dev STEP=029-create-gcp-secrets

Deprovision (Destroy)

make do-deprovision ENV=dev STEP=029-create-gcp-secrets

Plan Only

make do-tf-plan ENV=dev STEP=029-create-gcp-secrets

List State

make do-tf-state-list ENV=dev STEP=029-create-gcp-secrets

Provision All Environments

for env in inf dev tst prd; do
  make do-generate-config-for-step ENV=$env STEP=029-create-gcp-secrets
  make do-provision ENV=$env STEP=029-create-gcp-secrets
done

GCP Secrets Sync

Sync secret values from Google Sheet to GCP Secret Manager:

# Single environment
make do-gcp-sync-secrets ENV=dev

# Dry run (preview only)
make do-gcp-sync-secrets ENV=dev DRY_RUN=1

# All environments
for env in inf dev tst prd; do
  make do-gcp-sync-secrets ENV=$env
done

Git Operations

Pull All Repos

./run -a do_pull_all_app_repos

Push All Repos

./run -a do_push_all_app_repos

Running Tests

make test-api             # All API tests
make test-api-cov         # With coverage report
make test-api-payment     # Payment tests only
make test-api-debug       # Verbose output
make test-api-shell       # Shell into test container

Finding Shell Actions

# List all available actions
./run --help

# Search by keyword
SRCH=gcp ./run -a do_help_with
SRCH=deploy ./run -a do_help_with
SRCH=version ./run -a do_help_with

Health Checks

API Health

for env in inf dev tst prd; do
  echo -n "$env: "
  curl -s "https://$env.api.carpulsetracker.com/health" | jq -r '.status'
done

WUI Health

for env in inf dev tst; do
  echo -n "$env: "
  curl -s -o /dev/null -w "%{http_code}" "https://$env.carpulsetracker.com/index.html"
  echo ""
done
echo -n "prd: "
curl -s -o /dev/null -w "%{http_code}" "https://carpulsetracker.com/index.html"
echo ""

Monitoring GitHub Actions

# API CI
gh run list --workflow=ci.yaml --repo csitea/bnc-cpt-api

# API CD
gh run list --workflow=cd.yaml --repo csitea/bnc-cpt-api

# WUI CI/CD
gh run list --workflow=ci.yaml --repo csitea/bnc-cpt-wui

# Watch latest run
gh run watch --repo csitea/bnc-cpt-api
gh run watch --repo csitea/bnc-cpt-wui

Linear Issue Management

# Fetch issue details
ISSUE_ID=BNC-61 ./run -a do_linear_fetch_issue

# Close issue
ISSUE_ID=BNC-61 ./run -a do_linear_close_issue

# Close with comment
ISSUE_ID=BNC-61 COMMENT="Deployed to all envs" ./run -a do_linear_close_issue

Troubleshooting

Container Won't Start

# Check Docker logs
docker logs con-bnc-cpt-api
docker logs con-bnc-cpt-tf-runner

# Rebuild from scratch
make do-setup-api-no-cache

Terraform Runner Not Available

# Start it
make do-setup-tf-runner

# Verify it's running
docker ps | grep tf-runner

"Permission denied" on Docker Commands

# Ensure UID/GID are set
export UID=$(id -u) GID=$(id -g)