@crossdelta/infrastructure 0.2.11 → 0.2.12

package/README.md

@@ -3,15 +3,64 @@
 [![npm version](https://img.shields.io/npm/v/@crossdelta/infrastructure.svg)](https://www.npmjs.com/package/@crossdelta/infrastructure)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Infrastructure-as-Code helpers for deploying microservices to DigitalOcean App Platform with Pulumi.
+Infrastructure-as-Code helpers for deploying microservices to DigitalOcean with Pulumi.
+
+> **Note**: This is an MVP architecture optimized for simplicity and cost-efficiency.
+> For production with SLAs, consider managed services or HA clustering.
+
+## Architecture Overview
+
+```
++-----------------------------------------------------------------------------+
+|                              DigitalOcean                                   |
+|  +-----------------------------------------------------------------------+  |
+|  |                         App Platform                                  |  |
+|  |  +-------------+  +-------------+  +-------------+                   |  |
+|  |  |  frontend   |  |     api     |  |   worker    |                   |  |
+|  |  |  (public)   |  |  (public)   |  | (internal)  |                   |  |
+|  |  |   :3000     |  |   :4000     |  |   :4001     |                   |  |
+|  |  +-------------+  +-------------+  +-------------+                   |  |
+|  |         |                |                |                          |  |
+|  +---------|----------------|----------------|---------------------------+  |
+|            |                |                |                              |
+|            +----------------+----------------+                              |
+|                             |  VPC (private network)                        |
+|                             v                                               |
+|  +-----------------------------------------------------------------------+  |
+|  |                         Droplet                                       |  |
+|  |  +---------------------------------------------+                     |  |
+|  |  |              NATS + JetStream               |                     |  |
+|  |  |              :4222 (NATS)                   |                     |  |
+|  |  |              :8222 (HTTP monitoring)        |                     |  |
+|  |  +---------------------------------------------+                     |  |
+|  |                         |                                             |  |
+|  |                    +---------+                                        |  |
+|  |                    | Volume  |  (persistent storage)                  |  |
+|  |                    | /data   |                                        |  |
+|  |                    +---------+                                        |  |
+|  +-----------------------------------------------------------------------+  |
++-----------------------------------------------------------------------------+
+```
+
+### Platform Strategy
+
+| Platform | Use Case | Pros | Cons |
+|----------|----------|------|------|
+| **App Platform** | Stateless services (APIs, frontends) | Auto-scaling, zero-ops, built-in networking | No persistent volumes |
+| **Droplet** | Stateful services (NATS, databases) | Persistent volumes, full control | Manual management |
+
+**Why this split?** DigitalOcean App Platform doesn't support persistent volumes.
+Services like NATS with JetStream need persistent storage for message durability.
 
 ## Features
 
+- **Dual Platform Support** - Deploy to App Platform or Droplets from the same config
 - **Service Discovery** - Auto-discover service configs from `infra/services/*.ts`
 - **Type-safe Config** - Full TypeScript support with `ServiceConfig` type
 - **Smart Routing** - Automatic ingress rules for public services
-- **Internal Services** - Support for internal-only ports (no public exposure)
-- **Multi-Registry** - Docker Hub, GHCR, and DOCR image support
+- **VPC Networking** - Secure private communication between platforms
+- **Persistent Volumes** - Automatic volume creation and mounting for Droplets
+- **Config File Mounting** - Share config files between local dev and production
 - **URL Generation** - Auto-generate service URLs and port env vars
 
 ## Installation
@@ -21,17 +70,44 @@ npm install @crossdelta/infrastructure
 ```
 
 ## Quick Start
-### 1. Create a service config
+
+### 1. Create service configs
 
 ```typescript
-// infra/services/api-gateway.ts
+// infra/services/api.ts - App Platform (stateless)
 import type { ServiceConfig } from '@crossdelta/infrastructure'
 
 const config: ServiceConfig = {
-  name: 'api-gateway',
-  instanceSizeSlug: 'apps-s-1vcpu-0.5gb',
+  name: 'api',
   httpPort: 4000,
   ingressPrefix: '/api',
+  instanceSizeSlug: 'apps-s-1vcpu-0.5gb',
+}
+
+export default config
+```
+
+```typescript
+// infra/services/nats.ts - Droplet (stateful with persistence)
+import { dockerHubImage, type ServiceConfig } from '@crossdelta/infrastructure'
+import { readFileSync } from 'node:fs'
+
+const config: ServiceConfig = {
+  name: 'nats',
+  platform: 'droplet',
+  internalPorts: [4222, 8222],
+  internalUrl: 'nats://nats:4222',
+  image: dockerHubImage('nats', '2.10-alpine'),
+  runCommand: '-c /etc/nats/nats.conf',
+  droplet: {
+    size: 's-1vcpu-1gb',
+    volumes: [{ name: 'nats-data', mountPath: '/data', sizeGb: 10 }],
+    vpcPorts: [4222, 8222],
+    configFile: {
+      containerPath: '/etc/nats/nats.conf',
+      content: readFileSync('path/to/nats.conf', 'utf-8'),
+    },
+  },
 }
 
 export default config
@@ -46,60 +122,215 @@ import {
   buildIngressRules,
   buildServiceUrlEnvs,
   buildServicePortEnvs,
+  buildDropletServices,
+  filterByPlatform,
   discoverServices,
 } from '@crossdelta/infrastructure'
-import { App } from '@pulumi/digitalocean'
+import { App, Vpc } from '@pulumi/digitalocean'
 
+const region = 'fra1'
 const serviceConfigs = discoverServices('services')
 
+// Split services by platform
+const { appPlatformServices, dropletServices } = filterByPlatform(serviceConfigs)
+
+// Create VPC for private networking
+const vpc = new Vpc('platform-vpc', {
+  name: 'platform-vpc',
+  region,
+  ipRange: '10.10.10.0/24',
+})
+
+// Deploy Droplet services (stateful)
+const dropletResources = buildDropletServices({
+  serviceConfigs: dropletServices,
+  region,
+  vpcUuid: vpc.id,
+  projectName: 'my-platform',
+})
+
+// Get env vars for Droplet service URLs
+const dropletServiceEnvs = dropletResources.flatMap(r => [
+  { key: `${r.serviceName.toUpperCase()}_URL`, value: r.internalUrl },
+  { key: `${r.serviceName.toUpperCase()}_HOST`, value: r.privateIp },
+])
+
+// Deploy App Platform services (stateless)
 const app = new App('my-app', {
   spec: {
     name: 'my-platform',
-    region: 'fra',
+    region: region.replace(/\d+$/, ''), // 'fra1' -> 'fra'
     envs: [
-      ...buildServiceUrlEnvs(serviceConfigs),
-      ...buildServicePortEnvs(serviceConfigs),
+      ...buildServiceUrlEnvs(appPlatformServices),
+      ...buildServicePortEnvs(appPlatformServices),
+      ...dropletServiceEnvs,
     ],
-    services: buildServices({ serviceConfigs }),
-    ingress: { rules: buildIngressRules(serviceConfigs) },
+    services: buildServices({ serviceConfigs: appPlatformServices }),
+    ingress: { rules: buildIngressRules(appPlatformServices) },
   },
 })
 ```
 
+## ServiceConfig API
+
+The `ServiceConfig` type is the central configuration for all services:
+
+```typescript
+type ServiceConfig = {
+  /** Unique name of the service (required) */
+  name: string
+  
+  /** Deployment platform: 'app-platform' (default) or 'droplet' */
+  platform?: 'app-platform' | 'droplet'
+  
+  /** Public HTTP port with ingress routing (requires ingressPrefix) */
+  httpPort?: number
+  
+  /** Internal-only ports, not publicly accessible */
+  internalPorts?: number[]
+  
+  /** Ingress path prefix for public routing (e.g., '/api') */
+  ingressPrefix?: string
+  
+  /** Override internal URL (e.g., 'nats://nats:4222' for non-HTTP) */
+  internalUrl?: string
+  
+  /** Exclude from deployment */
+  skip?: boolean
+  
+  /** Custom image configuration */
+  image?: {
+    registryType: 'DOCKER_HUB' | 'GHCR' | 'DOCR'
+    registry: string      // e.g., 'library', 'myorg'
+    repository: string    // e.g., 'nats', 'platform/api'
+    tag: string           // e.g., '2.10-alpine', 'latest'
+  }
+  
+  /** Command to run in the container */
+  runCommand?: string
+  
+  /** App Platform: instance size (e.g., 'apps-s-1vcpu-0.5gb') */
+  instanceSizeSlug?: string
+  
+  /** Droplet-specific configuration */
+  droplet?: {
+    /** Droplet size (e.g., 's-1vcpu-1gb') */
+    size: string
+    
+    /** Persistent volumes */
+    volumes?: Array<{
+      name: string        // Volume name (unique)
+      mountPath: string   // Path in container (e.g., '/data')
+      sizeGb: number      // Size in GB
+    }>
+    
+    /** Ports to open in VPC firewall */
+    vpcPorts?: number[]
+    
+    /** Additional Docker run arguments */
+    dockerArgs?: string
+    
+    /** Config file to mount into container */
+    configFile?: {
+      containerPath: string  // Path in container
+      content: string        // File content
+    }
+  }
+}
+```
+
 ## Service Configuration Examples
 
-### Public Service
+### Public Service (App Platform)
 
 ```typescript
 const config: ServiceConfig = {
-  name: 'storefront',
+  name: 'frontend',
   httpPort: 3000,
   ingressPrefix: '/',
   instanceSizeSlug: 'apps-s-1vcpu-1gb',
 }
 ```
 
-### Internal Service
+### Internal Service (App Platform)
 
 ```typescript
 const config: ServiceConfig = {
-  name: 'orders',
+  name: 'worker',
   internalPorts: [4001],
   instanceSizeSlug: 'apps-s-1vcpu-0.5gb',
 }
 ```
 
-### Internal Service with Custom URL (e.g., NATS)
+### Stateful Service with Persistence (Droplet)
 
 ```typescript
+import { dockerHubImage, type ServiceConfig } from '@crossdelta/infrastructure'
+
 const config: ServiceConfig = {
   name: 'nats',
+  platform: 'droplet',
   internalPorts: [4222, 8222],
   internalUrl: 'nats://nats:4222',
-  instanceSizeSlug: 'apps-s-1vcpu-1gb',
+  image: dockerHubImage('nats', '2.10-alpine'),
+  runCommand: '-c /etc/nats/nats.conf',
+  droplet: {
+    size: 's-1vcpu-1gb',
+    volumes: [{ name: 'nats-data', mountPath: '/data', sizeGb: 10 }],
+    vpcPorts: [4222, 8222],
+    configFile: {
+      containerPath: '/etc/nats/nats.conf',
+      content: readFileSync('services/nats/nats.conf', 'utf-8'),
+    },
+  },
+}
+```
+
+### Config File Sharing (Local + Production)
+
+One of the key features is sharing configuration between local development and production:
+
+```
+services/nats/
+├── nats.conf              # Shared config (used by both)
+└── scripts/
+    └── start-dev.sh       # Local dev script
+```
+
+**nats.conf** (shared):
+```conf
+server_name: my-nats-server
+listen: 0.0.0.0:4222
+http: 0.0.0.0:8222
+
+jetstream {
+  store_dir: /data
+  max_mem: 1G
+  max_file: 10G
 }
 ```
 
+**start-dev.sh** (local):
+```bash
+docker run -d --name nats \
+  -v "$(pwd)/nats.conf:/etc/nats/nats.conf:ro" \
+  -v "$(pwd)/.nats-data:/data" \
+  -p 4222:4222 -p 8222:8222 \
+  nats:2.10-alpine -c /etc/nats/nats.conf
+```
+
+**infra/services/nats.ts** (production):
+```typescript
+droplet: {
+  configFile: {
+    containerPath: '/etc/nats/nats.conf',
+    content: readFileSync('services/nats/nats.conf', 'utf-8'),
+  },
+}
+```
+
+→ Same config file, same behavior, different environments.
+
 ## CLI: generate-env
 
 Generate `.env.local` and service-specific `env.ts` files for local development.
@@ -116,8 +347,6 @@ Add a script to your workspace `package.json`:
 }
 ```
 
-Or use `pf dev` which runs `generate-env` automatically before starting services.
-
 ### What it does
 
 1. Loads secrets from Pulumi config (dev stack)
@@ -132,21 +361,13 @@ Or use `pf dev` which runs `generate-env` automatically before starting services
 `.env.local`:
 ```bash
 # Service URLs (localhost for local development)
-API_GATEWAY_URL=http://localhost:4000
-STOREFRONT_URL=http://localhost:3000
+API_URL=http://localhost:4000
+FRONTEND_URL=http://localhost:3000
+NATS_URL=nats://localhost:4222
 
 # Service Ports
-API_GATEWAY_PORT=4000
-STOREFRONT_PORT=3000
-```
-
-`services/orders/src/env.ts`:
-```typescript
-import { getServicePort, getServiceUrl } from '@crossdelta/infrastructure/env'
-
-export const SERVICE_NAME = 'orders' as const
-export const getServicePort = (defaultPort = 8080) => _getServicePort(SERVICE_NAME, defaultPort)
-export const getServiceUrl = () => _getServiceUrl(SERVICE_NAME)
+API_PORT=4000
+FRONTEND_PORT=3000
 ```
 
 ## Runtime Helpers
@@ -156,27 +377,51 @@ Use `@crossdelta/infrastructure/env` in your services to read environment config
 ```typescript
 import { getServicePort, getServiceUrl } from '@crossdelta/infrastructure/env'
 
-// Get port from ORDERS_PORT env var (fallback: 8080)
-const port = getServicePort('orders', 8080)
+// Get port from WORKER_PORT env var (fallback: 8080)
+const port = getServicePort('worker', 8080)
 
-// Get URL from ORDERS_URL env var
-const url = getServiceUrl('orders')
+// Get URL from WORKER_URL env var
+const url = getServiceUrl('worker')
 ```
 
 These helpers work both locally (via `.env.local`) and in production (via DO App Platform env injection).
 
-## API
+## API Reference
 
 ### Main Export (`@crossdelta/infrastructure`)
 
 | Function | Description |
 |----------|-------------|
-| `discoverServices(dir)` | Auto-discover service configs (relative to cwd or absolute) |
+| `discoverServices(dir)` | Auto-discover service configs from directory |
 | `buildServices(options)` | Build App Platform service specs |
-| `buildIngressRules(configs)` | Generate ingress rules |
+| `buildIngressRules(configs)` | Generate ingress rules for public services |
 | `buildServiceUrlEnvs(configs)` | Create SERVICE_NAME_URL env vars |
 | `buildServicePortEnvs(configs)` | Create SERVICE_NAME_PORT env vars |
 | `buildLocalUrls(configs)` | Generate localhost URLs for local dev |
+| `filterByPlatform(configs)` | Split configs into App Platform and Droplet services |
+| `buildDropletServices(options)` | Create Droplet resources with volumes and firewall |
+| `dockerHubImage(repo, tag, registry?)` | Create Docker Hub image config (defaults to `library`) |
+
+### Droplet Builder Options
+
+```typescript
+buildDropletServices({
+  serviceConfigs: ServiceConfig[]  // Services with platform: 'droplet'
+  region: string                   // DO region (e.g., 'fra1')
+  vpcUuid: pulumi.Output<string>   // VPC ID for private networking
+  projectName: string              // Prefix for resource names
+})
+```
+
+Returns an array of:
+```typescript
+{
+  serviceName: string              // Service name
+  droplet: digitalocean.Droplet    // Created Droplet resource
+  privateIp: pulumi.Output<string> // Private IP in VPC
+  internalUrl: string              // URL for service discovery
+}
+```
 
 ### Env Export (`@crossdelta/infrastructure/env`)
 
@@ -185,6 +430,23 @@ These helpers work both locally (via `.env.local`) and in production (via DO App
 | `getServicePort(name, default)` | Read SERVICE_NAME_PORT from env |
 | `getServiceUrl(name)` | Read SERVICE_NAME_URL from env |
 
+## MVP Limitations & Future Improvements
+
+This architecture is designed for MVP/Beta deployments:
+
+| Current (MVP) | Future (Production) |
+|---------------|---------------------|
+| Single NATS Droplet | NATS Cluster (3 nodes) or Synadia Cloud |
+| No auto-healing | Kubernetes or managed service |
+| Manual scaling | Auto-scaling policies |
+| Basic monitoring | Prometheus/Grafana stack |
+
+**Cost estimate (MVP)**:
+- App Platform: ~$12-24/month (depending on instance sizes)
+- NATS Droplet: ~$6/month (s-1vcpu-1gb)
+- Volume: ~$1/month (10GB)
+- **Total**: ~$19-31/month
+
 ## License
 
 MIT

package/dist/helpers/droplet-builder.d.ts

@@ -0,0 +1,38 @@
+import * as digitalocean from '@pulumi/digitalocean';
+import * as pulumi from '@pulumi/pulumi';
+import type { ServiceConfig } from '../types';
+export interface DropletServiceResources {
+    droplet: digitalocean.Droplet;
+    volume?: digitalocean.Volume;
+    volumeAttachment?: digitalocean.VolumeAttachment;
+    firewall?: digitalocean.Firewall;
+    /** Private IP for VPC communication */
+    privateIp: pulumi.Output<string>;
+}
+export interface BuildDropletServicesOptions {
+    /** Service configs with platform: 'droplet' */
+    serviceConfigs: ServiceConfig[];
+    /** DigitalOcean region (e.g., 'fra1') */
+    region: string;
+    /** VPC UUID for private networking */
+    vpcUuid: pulumi.Input<string>;
+    /** SSH key IDs for Droplet access (optional) */
+    sshKeyIds?: pulumi.Input<pulumi.Input<string>[]>;
+    /** Registry credentials for private images (optional) */
+    registryCredentials?: pulumi.Output<string>;
+}
+/**
+ * Builds Droplet resources for services with platform: 'droplet'.
+ *
+ * Creates:
+ * - Droplet with Docker and cloud-init script
+ * - Volume(s) for persistent storage (if configured)
+ * - Firewall rules for VPC access
+ *
+ * @returns Map of service name to created resources
+ */
+export declare function buildDropletServices(options: BuildDropletServicesOptions): Map<string, DropletServiceResources>;
+/**
+ * Filters service configs by platform type.
+ */
+export declare function filterByPlatform(configs: ServiceConfig[], platform: 'app-platform' | 'droplet'): ServiceConfig[];

package/dist/helpers/index.d.ts

@@ -1,6 +1,7 @@
 export * from './config';
 export * from './discover-services';
 export * from './docker-hub-image';
+export * from './droplet-builder';
 export * from './image';
 export * from './service-builder';
 export * from './service-runtime';