cities-dev-demo

Demonstrates ephemeral dev environments on Control Plane with Cloud Wormhole connecting to a private RDS PostgreSQL instance — no VPN, no public database endpoint.

Developers get a full VS Code IDE in the browser (code-server) and Claude Code CLI, accessible via cpln port-forward. One command to spin up, one to tear down.

Architecture

Control Plane GVC: cities-demo
  └── workload: dev-<you>              ← disposable, created on demand
        ├── code-server (port 8443)    ← VS Code in browser
        ├── Flask app (port 8080)      ← the demo app
        ├── Claude Code CLI            ← AI-assisted development
        └── identity: cities-dev-id
              └── networkResource: rds-postgres
                    ↓ Cloud Wormhole
                    cpln agent (EC2 in VPC)
                    ↓
                    RDS PostgreSQL (private subnet, no public endpoint)

Prerequisites

• cpln CLI installed and authenticated (cpln profile get)
• Docker running
• envsubst available (brew install gettext on Mac)

Infrastructure (already deployed)

The terraform/ directory provisions:

• VPC with private + public subnets
• RDS PostgreSQL (db.t3.micro) in private subnet — no public endpoint
• EC2 instance running the cpln agent in the public subnet
• Security groups: agent egress-only, RDS accepts Postgres from agent only

Quick start

# Deploy ephemeral environment (build image, push, create workload)
make up

# Wait ~60s, then connect (opens VS Code in browser)
make connect

# Inside the IDE:
#   - Browse and edit files in VS Code
#   - Open terminal → run `claude` for Claude Code
#   - App is live at http://localhost:8080

# Tear down when done
make down

How Cloud Wormhole works here

1. cpln agent runs on an EC2 in the same VPC as RDS. It dials out to Control Plane's hub — no inbound ports, no public endpoint.
2. Identity (cpln/identity.yaml) declares a networkResource named rds-postgres that maps to the private RDS FQDN via the agent.
3. Workload sets DB_HOST=rds-postgres. Cloud Wormhole resolves this to the private RDS endpoint through the agent tunnel.

The app code has zero awareness of Wormhole. It just connects to rds-postgres:5432.

Customization

Variable	Default	Description
ORG	cpln-customer-demos	Control Plane org
GVC	cities-demo	Target GVC
LOCATION	aws-us-east-1	Deployment location
WORKLOAD_NAME	dev-<whoami>	Workload name