@celilo/e2e 0.1.0

package/src/docker-compose-generator.ts

@@ -0,0 +1,499 @@
+import { stringify } from 'yaml';
+import type { MachineSpec, NetworkConfig, TopologyPreset } from './types';
+import { ZONE_GATEWAYS } from './types';
+
+const NETWORK_DRIVER_OPTS = {
+  'com.docker.network.bridge.enable_ip_masquerade': 'false',
+  'com.docker.network.endpoint.sysctls': 'net.ipv4.conf.IFNAME.rp_filter=0',
+};
+
+const ROUTER_SYSCTLS = {
+  'net.ipv4.ip_forward': '1',
+  'net.ipv4.conf.all.rp_filter': '0',
+};
+
+function networkDef(subnet: string, gateway: string) {
+  return {
+    driver: 'bridge',
+    driver_opts: NETWORK_DRIVER_OPTS,
+    ipam: { config: [{ subnet, gateway }] },
+  };
+}
+
+/**
+ * Image tag prefix for pre-built e2e images. When images with these
+ * tags exist locally, `docker compose build` skips rebuilding them.
+ * The e2e-build script creates these tags; e2e-save/e2e-load persist
+ * them across colima restarts.
+ */
+const IMAGE_PREFIX = 'celilo-e2e';
+
+function imageTag(dockerfile: string): string {
+  // docker/Dockerfile.management -> celilo-e2e/management
+  const name = dockerfile.replace('docker/Dockerfile.', '');
+  return `${IMAGE_PREFIX}/${name}`;
+}
+
+function baseService(opts: {
+  build?: { context: string; dockerfile: string };
+  image?: string;
+  networks: Record<string, { ipv4_address: string }>;
+  cap_add?: string[];
+  sysctls?: Record<string, string>;
+  volumes?: string[];
+  command?: string;
+  depends_on?: string[];
+  environment?: Record<string, string>;
+  tmpfs?: string[];
+  privileged?: boolean;
+}) {
+  // Auto-assign an image tag from the Dockerfile name so Docker can
+  // skip builds when pre-built images exist.
+  const service: Record<string, unknown> = { ...opts, restart: 'unless-stopped' };
+  if (opts.build && !opts.image) {
+    service.image = imageTag(opts.build.dockerfile);
+  }
+  return service;
+}
+
+// ---------------------------------------------------------------------------
+// Shared infrastructure project name. Used by both the shared infra
+// manager and per-test compose files (to reference external networks).
+// ---------------------------------------------------------------------------
+
+export const SHARED_PROJECT_NAME = 'celilo-e2e-shared';
+
+/** Docker network names as created by the shared infrastructure project */
+export const SHARED_NETWORKS = {
+  'isp-external': `${SHARED_PROJECT_NAME}_isp-external`,
+  'internet-external': `${SHARED_PROJECT_NAME}_internet-external`,
+  'real-internet': `${SHARED_PROJECT_NAME}_real-internet`,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Topology: services south of fw-ext (firewalls, ISP routers)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default topology: fw-isp (greenwave) + fw-main (iptables)
+ * Two-layer NAT: internet → fw-isp → fw-main → target
+ */
+function defaultTopologyServices(): Record<string, unknown> {
+  return {
+    'fw-main': baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.firewall' },
+      networks: {
+        internal: { ipv4_address: '192.168.0.254' },
+        dmz: { ipv4_address: '10.0.10.1' },
+        app: { ipv4_address: '10.0.20.1' },
+        secure: { ipv4_address: '10.0.30.1' },
+      },
+      cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      sysctls: ROUTER_SYSCTLS,
+      volumes: ['ssh-keys:/ssh-keys:ro'],
+    }),
+    'fw-isp': baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.greenwave-sim' },
+      networks: {
+        internal: { ipv4_address: '192.168.0.1' },
+        'isp-external': { ipv4_address: '100.100.0.100' },
+      },
+      cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      sysctls: ROUTER_SYSCTLS,
+      volumes: ['ssh-keys:/ssh-keys:ro'],
+    }),
+  };
+}
+
+/**
+ * Direct internet topology: fw-main has external interface, no fw-isp
+ * Single-layer NAT: internet → fw-main → target
+ * Management routes default through fw-main instead of fw-isp
+ */
+function directInternetTopologyServices(): Record<string, unknown> {
+  return {
+    'fw-main': baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.firewall' },
+      networks: {
+        internal: { ipv4_address: '192.168.0.254' },
+        dmz: { ipv4_address: '10.0.10.1' },
+        app: { ipv4_address: '10.0.20.1' },
+        secure: { ipv4_address: '10.0.30.1' },
+        'isp-external': { ipv4_address: '100.100.0.100' },
+      },
+      cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      sysctls: ROUTER_SYSCTLS,
+      volumes: ['ssh-keys:/ssh-keys:ro'],
+    }),
+    // No fw-isp — fw-main handles external routing directly
+  };
+}
+
+const TOPOLOGY_SERVICES: Record<TopologyPreset, () => Record<string, unknown>> = {
+  default: defaultTopologyServices,
+  'direct-internet': directInternetTopologyServices,
+};
+
+// ---------------------------------------------------------------------------
+// Shared infrastructure compose (DNS, Pebble, apt-cache, fw-ext)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate the compose YAML for shared infrastructure that runs once
+ * per test suite. Contains: fw-ext, DNS hierarchy, Pebble ACME, apt-cache.
+ * Owns the isp-external, internet-external, and real-internet networks.
+ */
+export function generateSharedInfraYaml(): string {
+  const networks: Record<string, unknown> = {
+    'isp-external': networkDef('100.100.0.0/24', '100.100.0.250'),
+    'internet-external': networkDef('100.64.0.0/24', '100.64.0.250'),
+    'real-internet': {
+      driver: 'bridge',
+      ipam: { config: [{ subnet: '172.30.0.0/24' }] },
+    },
+  };
+
+  const volumes: Record<string, unknown> = {
+    'apt-cache': { driver: 'local' },
+  };
+
+  const services: Record<string, unknown> = {};
+
+  services['fw-ext'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.router' },
+    networks: {
+      'isp-external': { ipv4_address: '100.100.0.101' },
+      'internet-external': { ipv4_address: '100.64.0.1' },
+      'real-internet': { ipv4_address: '172.30.0.5' },
+    },
+    cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+    sysctls: ROUTER_SYSCTLS,
+  });
+
+  services['comcast-resolver'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.resolver' },
+    networks: {
+      'isp-external': { ipv4_address: '100.100.0.1' },
+      'real-internet': { ipv4_address: '172.30.0.4' },
+    },
+    cap_add: ['NET_ADMIN'],
+  });
+
+  services['root-dns'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.authoritative-dns' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.53' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      './config/dns/knot-root.conf:/config/knot.conf:ro',
+      './config/dns/root.zone:/config/root.zone:ro',
+    ],
+  });
+
+  services['tld-dns'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.authoritative-dns' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.54' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      './config/dns/knot-tld.conf:/config/knot.conf:ro',
+      './config/dns/com.zone:/config/com.zone:ro',
+      './config/dns/org.zone:/config/org.zone:ro',
+    ],
+  });
+
+  services['namecheap-dns'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.namecheap-dns' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.55' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      './config/dns/knot-namecheap.conf:/config/knot.conf:ro',
+      './config/dns/iamtheinternet.org.zone:/config/iamtheinternet.org.zone',
+      './config/dns/park-your-domain.com.zone:/config/park-your-domain.com.zone',
+    ],
+  });
+
+  services['apt-cache'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.apt-cache' },
+    networks: {
+      'internet-external': { ipv4_address: '100.64.0.2' },
+      'real-internet': { ipv4_address: '172.30.0.2' },
+    },
+    cap_add: ['NET_ADMIN'],
+    volumes: ['apt-cache:/var/cache/apt-cacher-ng'],
+  });
+
+  services.letsencrypt = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.pebble' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.100' } },
+    cap_add: ['NET_ADMIN'],
+    command: '-config /config/pebble-config.json -dnsserver 100.100.0.1:53',
+    volumes: [
+      './config/pebble/pebble-config.json:/config/pebble-config.json:ro',
+      './config/pebble/pebble-tls.crt:/config/pebble-tls.crt:ro',
+      './config/pebble/pebble-tls.key:/config/pebble-tls.key:ro',
+    ],
+  });
+
+  const compose = { networks, volumes, services };
+  return stringify(compose, { lineWidth: 120 });
+}
+
+// ---------------------------------------------------------------------------
+// Per-test compose generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate the compose YAML for a single test's containers.
+ * References the shared infrastructure's isp-external network as external.
+ * Creates its own internal, dmz, app, secure networks.
+ */
+export function generateTestComposeYaml(config: NetworkConfig, celiloRoot = '..'): string {
+  const networks: Record<string, unknown> = {
+    internal: networkDef('192.168.0.0/24', '192.168.0.250'),
+    dmz: networkDef('10.0.10.0/24', '10.0.10.250'),
+    app: networkDef('10.0.20.0/24', '10.0.20.250'),
+    secure: networkDef('10.0.30.0/24', '10.0.30.250'),
+    // isp-external is owned by the shared infra project — reference it
+    'isp-external': {
+      external: true,
+      name: SHARED_NETWORKS['isp-external'],
+    },
+  };
+
+  const volumes: Record<string, unknown> = {
+    'ssh-keys': { driver: 'local' },
+  };
+
+  const services: Record<string, unknown> = {};
+
+  // --- Management (always present) ---
+  const managementDefaultGw = config.topology === 'direct-internet' ? '192.168.0.254' : '192.168.0.1';
+
+  services.management = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.management' },
+    networks: { internal: { ipv4_address: '192.168.0.100' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      `${celiloRoot}:/celilo`,
+      'ssh-keys:/ssh-keys',
+      ...(config.managementVolumes ?? []),
+    ],
+    environment: {
+      DDNS_ENDPOINT: 'http://100.64.0.55:8080/update',
+      DEFAULT_GATEWAY: managementDefaultGw,
+    },
+  });
+
+  // --- Topology-specific infrastructure (south of fw-ext) ---
+  const topologyFn = TOPOLOGY_SERVICES[config.topology] || TOPOLOGY_SERVICES.default;
+  Object.assign(services, topologyFn());
+
+  // --- Dynamic test machines ---
+  const allMachines = [
+    ...config.dmzMachines,
+    ...config.appMachines,
+    ...config.secureMachines,
+    ...config.internalMachines,
+  ];
+
+  for (const machine of allMachines) {
+    const zoneNetwork = machine.zone;
+    const gateway = ZONE_GATEWAYS[machine.zone];
+
+    const isAppZone = machine.zone === 'app';
+    const dockerfile = isAppZone
+      ? 'docker/Dockerfile.target-machine-docker'
+      : 'docker/Dockerfile.target-machine';
+
+    const machineVolumes = ['ssh-keys:/ssh-keys:ro'];
+    if (isAppZone) {
+      machineVolumes.push('./docker-image-cache:/docker-image-cache:ro');
+    }
+
+    services[machine.name] = baseService({
+      build: { context: '.', dockerfile },
+      networks: { [zoneNetwork]: { ipv4_address: machine.ip } },
+      privileged: true,
+      volumes: machineVolumes,
+      environment: { GATEWAY: gateway },
+      tmpfs: ['/run', '/run/lock', '/tmp'],
+    });
+  }
+
+  // --- Optional DHCP client ---
+  if (config.dhcpClient) {
+    services['dhcp-client'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.dhcp-client' },
+      networks: { internal: { ipv4_address: '192.168.0.210' } },
+      cap_add: ['NET_ADMIN'],
+    });
+  }
+
+  const compose = { networks, volumes, services };
+  return stringify(compose, { lineWidth: 120 });
+}
+
+// ---------------------------------------------------------------------------
+// Legacy: monolithic compose (kept for standalone/fallback use)
+// ---------------------------------------------------------------------------
+
+export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): string {
+  const networks: Record<string, unknown> = {
+    internal: networkDef('192.168.0.0/24', '192.168.0.250'),
+    dmz: networkDef('10.0.10.0/24', '10.0.10.250'),
+    app: networkDef('10.0.20.0/24', '10.0.20.250'),
+    secure: networkDef('10.0.30.0/24', '10.0.30.250'),
+    'isp-external': networkDef('100.100.0.0/24', '100.100.0.250'),
+    'internet-external': networkDef('100.64.0.0/24', '100.64.0.250'),
+    'real-internet': {
+      driver: 'bridge',
+      ipam: { config: [{ subnet: '172.30.0.0/24' }] },
+    },
+  };
+
+  const volumes: Record<string, unknown> = {
+    'ssh-keys': { driver: 'local' },
+    'apt-cache': { driver: 'local' },
+  };
+
+  const services: Record<string, unknown> = {};
+
+  const managementDefaultGw = config.topology === 'direct-internet' ? '192.168.0.254' : '192.168.0.1';
+
+  services.management = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.management' },
+    networks: { internal: { ipv4_address: '192.168.0.100' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      `${celiloRoot}:/celilo`,
+      'ssh-keys:/ssh-keys',
+      ...(config.managementVolumes ?? []),
+    ],
+    environment: {
+      DDNS_ENDPOINT: 'http://100.64.0.55:8080/update',
+      DEFAULT_GATEWAY: managementDefaultGw,
+    },
+  });
+
+  const topologyFn = TOPOLOGY_SERVICES[config.topology] || TOPOLOGY_SERVICES.default;
+  Object.assign(services, topologyFn());
+
+  services['fw-ext'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.router' },
+    networks: {
+      'isp-external': { ipv4_address: '100.100.0.101' },
+      'internet-external': { ipv4_address: '100.64.0.1' },
+      'real-internet': { ipv4_address: '172.30.0.5' },
+    },
+    cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+    sysctls: ROUTER_SYSCTLS,
+  });
+
+  services['comcast-resolver'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.resolver' },
+    networks: {
+      'isp-external': { ipv4_address: '100.100.0.1' },
+      'real-internet': { ipv4_address: '172.30.0.4' },
+    },
+    cap_add: ['NET_ADMIN'],
+  });
+
+  services['root-dns'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.authoritative-dns' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.53' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      './config/dns/knot-root.conf:/config/knot.conf:ro',
+      './config/dns/root.zone:/config/root.zone:ro',
+    ],
+  });
+
+  services['tld-dns'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.authoritative-dns' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.54' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      './config/dns/knot-tld.conf:/config/knot.conf:ro',
+      './config/dns/com.zone:/config/com.zone:ro',
+      './config/dns/org.zone:/config/org.zone:ro',
+    ],
+  });
+
+  services['namecheap-dns'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.namecheap-dns' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.55' } },
+    cap_add: ['NET_ADMIN'],
+    volumes: [
+      './config/dns/knot-namecheap.conf:/config/knot.conf:ro',
+      './config/dns/iamtheinternet.org.zone:/config/iamtheinternet.org.zone',
+      './config/dns/park-your-domain.com.zone:/config/park-your-domain.com.zone',
+    ],
+  });
+
+  services['apt-cache'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.apt-cache' },
+    networks: {
+      'internet-external': { ipv4_address: '100.64.0.2' },
+      'real-internet': { ipv4_address: '172.30.0.2' },
+    },
+    cap_add: ['NET_ADMIN'],
+    volumes: ['apt-cache:/var/cache/apt-cacher-ng'],
+  });
+
+  services.letsencrypt = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.pebble' },
+    networks: { 'internet-external': { ipv4_address: '100.64.0.100' } },
+    cap_add: ['NET_ADMIN'],
+    command: '-config /config/pebble-config.json -dnsserver 100.100.0.1:53',
+    volumes: [
+      './config/pebble/pebble-config.json:/config/pebble-config.json:ro',
+      './config/pebble/pebble-tls.crt:/config/pebble-tls.crt:ro',
+      './config/pebble/pebble-tls.key:/config/pebble-tls.key:ro',
+    ],
+  });
+
+  const allMachines = [
+    ...config.dmzMachines,
+    ...config.appMachines,
+    ...config.secureMachines,
+    ...config.internalMachines,
+  ];
+
+  for (const machine of allMachines) {
+    const zoneNetwork = machine.zone;
+    const gateway = ZONE_GATEWAYS[machine.zone];
+
+    const isAppZone = machine.zone === 'app';
+    const dockerfile = isAppZone
+      ? 'docker/Dockerfile.target-machine-docker'
+      : 'docker/Dockerfile.target-machine';
+
+    const machineVolumes = ['ssh-keys:/ssh-keys:ro'];
+    if (isAppZone) {
+      machineVolumes.push('./docker-image-cache:/docker-image-cache:ro');
+    }
+
+    services[machine.name] = baseService({
+      build: { context: '.', dockerfile },
+      networks: { [zoneNetwork]: { ipv4_address: machine.ip } },
+      privileged: true,
+      volumes: machineVolumes,
+      environment: { GATEWAY: gateway },
+      tmpfs: ['/run', '/run/lock', '/tmp'],
+    });
+  }
+
+  if (config.dhcpClient) {
+    services['dhcp-client'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.dhcp-client' },
+      networks: { internal: { ipv4_address: '192.168.0.210' } },
+      cap_add: ['NET_ADMIN'],
+    });
+  }
+
+  const compose = { networks, volumes, services };
+  return stringify(compose, { lineWidth: 120 });
+}
+
+export function getAllMachines(config: NetworkConfig): MachineSpec[] {
+  return [...config.dmzMachines, ...config.appMachines, ...config.secureMachines, ...config.internalMachines];
+}

package/src/fixtures.ts

@@ -0,0 +1,40 @@
+import { NetworkBuilder, network } from './network-builder';
+
+/** Single caddy machine in the DMZ — basic web server deployment */
+export const CADDY_DEPLOYMENT = (): NetworkBuilder => network().dmz({ caddy: '10.0.10.10' });
+
+/** Full stack: web server, identity provider, database */
+export const FULL_STACK = (): NetworkBuilder =>
+  network()
+    .dmz({ caddy: '10.0.10.10' })
+    .app({ idp: '10.0.20.100' })
+    .secure({ db: '10.0.30.50' });
+
+/** Minimal: no dynamic machines, just fixed infrastructure */
+export const INFRASTRUCTURE_ONLY = (): NetworkBuilder => network();
+
+/** Caddy + Authentik: web server in DMZ, identity provider in app zone */
+export const AUTHENTIK_DEPLOYMENT = (): NetworkBuilder =>
+  network()
+    .dmz({ caddy: '10.0.10.10' })
+    .app({ authentik: '10.0.20.30' });
+
+/** Multiple DMZ machines for testing multi-service deployments */
+export const MULTI_DMZ = (): NetworkBuilder =>
+  network().dmz({
+    caddy: '10.0.10.10',
+    'web-app': '10.0.10.20',
+  });
+
+/** Technitium DNS + Caddy: internal DNS resolver + full web stack */
+export const TECHNITIUM_STACK = (): NetworkBuilder =>
+  network()
+    .internal({ 'dns-int': '192.168.0.53' })
+    .dmz({ caddy: '10.0.10.10' });
+
+/** Technitium DNS with DHCP client: tests DHCP DNS propagation */
+export const TECHNITIUM_DHCP_STACK = (): NetworkBuilder =>
+  network()
+    .internal({ 'dns-int': '192.168.0.53' })
+    .dmz({ caddy: '10.0.10.10' })
+    .withDhcpClient();

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @celilo/e2e — E2E test infrastructure for Celilo-deployed applications.
+ *
+ * Provides a simulated internet environment in Docker with:
+ * - DNS hierarchy (root → TLD → registrar → recursive resolver)
+ * - ACME server (Pebble, simulating Let's Encrypt)
+ * - APT cache (speeds up package installs in containers)
+ * - Firewall topology (ISP router, main firewall, zone routing)
+ * - Target machines (systemd-based containers for deployment)
+ *
+ * Usage:
+ *   import { network } from '@celilo/e2e';
+ *
+ *   const net = await network()
+ *     .dmz({ caddy: '10.0.10.10' })
+ *     .app({ myapp: '10.0.20.10' })
+ *     .start();
+ *
+ *   await net.celilo('module deploy myapp --no-interactive');
+ *   // ... assertions ...
+ *   await net.stop();
+ */
+
+// Builder API
+export { network, NetworkBuilder } from './network-builder';
+
+// Types
+export type {
+  NetworkConfig,
+  NetworkHandle,
+  ExecResult,
+  MachineSpec,
+  Zone,
+  TopologyPreset,
+} from './types';
+export { ZONE_GATEWAYS, ZONE_SUBNETS } from './types';
+
+// Common fixtures
+export {
+  CADDY_DEPLOYMENT,
+  FULL_STACK,
+  INFRASTRUCTURE_ONLY,
+  AUTHENTIK_DEPLOYMENT,
+  MULTI_DMZ,
+  TECHNITIUM_STACK,
+  TECHNITIUM_DHCP_STACK,
+} from './fixtures';
+
+// Shared infrastructure management (for test runners)
+export { ensureSharedInfra, stopSharedInfra, isSharedInfraRunning } from './shared-infra';
+
+// Low-level (for custom compose generation)
+export {
+  generateSharedInfraYaml,
+  generateTestComposeYaml,
+  generateComposeYaml,
+  SHARED_PROJECT_NAME,
+  SHARED_NETWORKS,
+} from './docker-compose-generator';

package/src/network-builder.ts

@@ -0,0 +1,91 @@
+import { startNetwork } from './container-manager';
+import type { NetworkConfig, NetworkHandle, TopologyPreset } from './types';
+
+export class NetworkBuilder {
+  private config: NetworkConfig = {
+    topology: 'default',
+    dmzMachines: [],
+    appMachines: [],
+    secureMachines: [],
+    internalMachines: [],
+    dhcpClient: false,
+    domain: 'iamtheinternet.org',
+    ddnsPassword: 'test123',
+    verifyRouting: process.env.VERIFY_ROUTING === '1',
+    managementVolumes: [],
+  };
+
+  topology(preset: TopologyPreset): this {
+    this.config.topology = preset;
+    return this;
+  }
+
+  dmz(machines: Record<string, string>): this {
+    for (const [name, ip] of Object.entries(machines)) {
+      this.config.dmzMachines.push({ name, ip, zone: 'dmz' });
+    }
+    return this;
+  }
+
+  app(machines: Record<string, string>): this {
+    for (const [name, ip] of Object.entries(machines)) {
+      this.config.appMachines.push({ name, ip, zone: 'app' });
+    }
+    return this;
+  }
+
+  secure(machines: Record<string, string>): this {
+    for (const [name, ip] of Object.entries(machines)) {
+      this.config.secureMachines.push({ name, ip, zone: 'secure' });
+    }
+    return this;
+  }
+
+  internal(machines: Record<string, string>): this {
+    for (const [name, ip] of Object.entries(machines)) {
+      this.config.internalMachines.push({ name, ip, zone: 'internal' });
+    }
+    return this;
+  }
+
+  withDhcpClient(): this {
+    this.config.dhcpClient = true;
+    return this;
+  }
+
+  domain(domain: string): this {
+    this.config.domain = domain;
+    return this;
+  }
+
+  withRoutingVerification(): this {
+    this.config.verifyRouting = true;
+    return this;
+  }
+
+  /** Mount a host directory into the management container */
+  mount(hostPath: string, containerPath: string): this {
+    this.config.managementVolumes.push(`${hostPath}:${containerPath}`);
+    return this;
+  }
+
+  /**
+   * Set the path to the Celilo project root. This directory is mounted
+   * into the management container at /celilo, providing access to the
+   * Celilo CLI and module source code.
+   *
+   * If not set, auto-detected by walking up from the @celilo/e2e package.
+   */
+  celilo(rootPath: string): this {
+    this.config.celiloRoot = rootPath;
+    return this;
+  }
+
+  async start(): Promise<NetworkHandle> {
+    return startNetwork(this.config);
+  }
+}
+
+export function network(): NetworkBuilder {
+  return new NetworkBuilder();
+}