@mesh-tech/mesh-cli 0.1.1 → 0.12.1

package/stack/docker-compose.hub.yml

@@ -0,0 +1,134 @@
+# Local Hub overlay (`mesh start --with-hub`).
+#
+# Images are built from the published @mesh-tech/hub tarball on first use
+# (see hub-local.ts) — the interim path until the hub pipeline publishes
+# pullable images. Requires one-time registry access (mesh registry login);
+# the core profile stays zero-access without this overlay.
+#
+# The Hub reads the SAME local fabric the apps use: SSM registry via
+# ministack (x-local-aws-env in the base file), the seeded `hub` database,
+# Temporal, SpiceDB — and the local observability backends (Loki logs,
+# Tempo traces, Prometheus metrics via the base file's OTel collector), so
+# the Hub's operational views run the exact hosted code paths. Only the
+# K8s-API views (pod state/metrics) have no local backend.
+#
+# No HUB_TENANT here on purpose: a local platform is a STANDALONE hub, so
+# hub-api resolves the single-tenant conventions ({tenant}-{env}-{app} for
+# K8s + Temporal namespaces) that everything local creates — zero
+# local-vs-hosted translation.
+
+services:
+  hub-api:
+    image: mesh-local-hub-api:${MESH_HUB_VERSION:-latest}
+    ports:
+      # 4568 host-side: the 3000 range belongs to `mesh dev` app services
+      - '4568:3002'
+    environment:
+      AWS_ENDPOINT_URL: http://ministack:4566
+      AWS_REGION: us-east-2
+      AWS_ACCESS_KEY_ID: test
+      AWS_SECRET_ACCESS_KEY: test
+      PORT: 3002
+      PULUMI_STATE_BUCKET: mesh-local-artifacts
+      DATABASE_URL: postgres://postgres:postgres@database:5432/hub?sslmode=disable
+      OPS_DB_HOST: database
+      OPS_DB_PORT: 5432
+      OPS_DB_NAME: hub
+      OPS_DB_USER: postgres
+      DATABASE_PASSWORD: postgres
+      PGSSLMODE: disable
+      TEMPORAL_ADDRESS: temporal:7233
+      TEMPORAL_NAMESPACE: local-dev
+      TEMPORAL_UI_URL: http://localhost:8233
+      LOKI_URL: http://loki:3100
+      TEMPO_URL: http://tempo:3200
+      PROMETHEUS_URL: http://prometheus:9090
+      # The REAL issuer URL (what `mesh login local` tokens carry). Valid
+      # inside the container via the Dockerfile's loopback forward to the
+      # zitadel service — Zitadel routes by Host header, so the issuer host
+      # must be `localhost` everywhere, exactly like the hosted public URL.
+      ZITADEL_ISSUER: http://localhost:8080
+      SPICEDB_ENDPOINT: spicedb:50051
+      SPICEDB_HTTP_ENDPOINT: http://spicedb:8443
+      SPICEDB_HTTP_SCHEME: http
+      SPICEDB_PRESHARED_KEY: local-dev-key
+      CORS_ORIGINS: http://localhost:${MESH_HUB_PORT:-9000}
+      MESH_LOCAL: "1"
+    depends_on:
+      database:
+        condition: service_healthy
+      ministack:
+        condition: service_healthy
+    networks:
+      - mesh_network
+
+  hub-ui:
+    image: mesh-local-hub-ui:${MESH_HUB_VERSION:-latest}
+    environment:
+      PORT: 9000
+      API_URL: http://hub-api:3002
+      # Browser-facing API base (SSR link env is in-network; the browser
+      # needs the host-published port).
+      PUBLIC_API_URL: http://localhost:4568
+      AGENT_API_URL: http://hub-api:3002
+      MESH_LOCAL: "1"
+    depends_on:
+      - hub-api
+    networks:
+      - mesh_network
+
+  # oauth2-proxy in front of the Hub UI — the SAME sidecar mesh.apps.Service
+  # deploys with `auth.provider: "mesh"` (image + flags mirrored from
+  # Service.ts; local deltas: cookie-secure=false because http, in-network
+  # upstream instead of localhost, and the roles scope the hub reads).
+  # Serves the Hub at http://localhost:9000: unauthenticated browsers land on
+  # the local Zitadel login, then get X-Forwarded-Access-Token / -User /
+  # -Email + Authorization headers forwarded — exactly like deployed.
+  hub-auth:
+    # Built locally from stack/hub/Dockerfile.auth (public images only):
+    # oauth2-proxy v7.7.1 + the in-container loopback forward that makes the
+    # real issuer URL valid here (Zitadel routes by Host header).
+    image: mesh-local-hub-auth:v7.7.1-r1
+    restart: unless-stopped
+    ports:
+      # MESH_HUB_PORT lets this Hub run beside another process that owns
+      # 9000 (e.g. a hub-ui dev server from a different checkout). The CLI's
+      # status probes + Zitadel seeding read the same variable.
+      - '${MESH_HUB_PORT:-9000}:4180'
+    command:
+      - --http-address=0.0.0.0:4180
+      - --upstream=http://hub-ui:9000
+      - --provider=oidc
+      # The ONE issuer URL tokens carry; valid in-container via the
+      # baked-in loopback forward.
+      - --oidc-issuer-url=http://localhost:8080
+      - --scope=openid email profile urn:zitadel:iam:org:project:roles
+      - --email-domain=*
+      # RP-initiated logout: hub-ui's /logout redirects through
+      # /oauth2/sign_out?rd=<issuer end_session>; rd hosts must be
+      # whitelisted (same flag the Service sidecar sets in the cloud).
+      - --whitelist-domain=localhost:8080
+      - --pass-authorization-header=true
+      - --pass-access-token=true
+      - --pass-user-headers=true
+      - --cookie-secure=false
+      - --cookie-samesite=lax
+      - --cookie-refresh=4h
+      - --cookie-expire=12h
+      - --skip-jwt-bearer-tokens=true
+      - --skip-provider-button=true
+      - --silence-ping-logging=true
+      - --auth-logging=true
+      - --standard-logging=true
+      - --redirect-url=http://localhost:${MESH_HUB_PORT:-9000}/oauth2/callback
+    environment:
+      OAUTH2_PROXY_CLIENT_ID: ${MESH_HUB_OAUTH2_CLIENT_ID:-unseeded}
+      OAUTH2_PROXY_CLIENT_SECRET: ${MESH_HUB_OAUTH2_CLIENT_SECRET:-unseeded}
+      # Placeholder (raw 32 bytes) keeps the container from crash-looping
+      # pre-seed; the CLI always passes the real persisted secret
+      # (hub-auth.json).
+      OAUTH2_PROXY_COOKIE_SECRET: ${MESH_HUB_OAUTH2_COOKIE_SECRET:-local-dev-placeholder-cookie-32b}
+    depends_on:
+      - hub-ui
+    networks:
+      - mesh_network

package/stack/docker-compose.yml

@@ -0,0 +1,447 @@
+# Mesh full-local platform (`mesh start`).
+#
+# Shipped inside @mesh-tech/mesh-cli so any repo can run the platform locally
+# with only Docker installed — no AWS credentials, no VPN, no Pulumi state.
+# Evolved from tools/local/docker-compose.yml in mesh-platform; every image is
+# pullable (no monorepo build contexts). The codec server and Temporal UI
+# gateway require monorepo image builds and join the stack once their images
+# are published.
+#
+# Discovery fabric: ministack (MIT-licensed AWS emulator) provides SSM
+# Parameter Store + Secrets Manager + S3 so the registry
+# (/mesh-platform/{tenant}/{env}/…) works locally with unchanged code paths —
+# services point at it via the SDK-native AWS_ENDPOINT_URL_* env overrides.
+# `mesh start` seeds tenant `local` / env `dev`.
+#
+# SECURITY: every credential in this stack (postgres/postgres, test/test AWS
+# keys, the Zitadel masterkey, SpiceDB's local-dev-key, permissive CORS) is a
+# LOCAL-ONLY default. Never reuse any of them outside this compose project —
+# deployed platforms mint their own secrets. Data/secret ports are bound to
+# 127.0.0.1 so none of this is reachable from the LAN.
+name: mesh-local
+
+# AWS wiring for in-network services (Hub API/worker join the stack once
+# their images are published): merge this anchor into a service's environment
+# and its AWS SDK clients hit the local fabric with zero code changes —
+# AWS_ENDPOINT_URL is the SDK-native endpoint override.
+x-local-aws-env: &local-aws-env
+  AWS_ENDPOINT_URL: http://ministack:4566
+  AWS_REGION: us-east-2
+  AWS_ACCESS_KEY_ID: test
+  AWS_SECRET_ACCESS_KEY: test
+
+services:
+  database:
+    image: postgres:17@sha256:a426e44bac0b759c95894d68e1a0ac03ecc20b619f498a91aae373bf06d8508d
+    ports:
+      - '127.0.0.1:5433:5432'
+    environment:
+      PGUSER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: temporal
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./init:/docker-entrypoint-initdb.d
+    networks:
+      - mesh_network
+    healthcheck:
+      # Single-string CMD-SHELL (an array's extra elements are ignored shell
+      # positionals) probing over TCP: the entrypoint's temporary initdb-phase
+      # server is socket-only, so -h 127.0.0.1 can't go green until the final
+      # server is up — after /docker-entrypoint-initdb.d has created the
+      # spicedb/app/hub databases spicedb-migrate needs.
+      test: ['CMD-SHELL', 'pg_isready -h 127.0.0.1 -d temporal -U postgres']
+      interval: '10s'
+      timeout: '30s'
+      retries: 5
+      start_period: '20s'
+
+  memcached:
+    image: memcached:1.6-alpine@sha256:c29847751abb41f4c268c84fb3087fee05d4edcbda44409ccb5086e26148e8a7
+    ports:
+      - '11211:11211'
+    networks:
+      - mesh_network
+    command: -m 128
+    healthcheck:
+      test: ['CMD', 'nc', '-z', 'localhost', '11211']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+  elasticsearch:
+    image: opensearchproject/opensearch:2.11.1
+    ports:
+      - '9200:9200'
+    environment:
+      - cluster.name=temporal-elasticsearch
+      - discovery.type=single-node
+      - bootstrap.memory_lock=true
+      - "OPENSEARCH_JAVA_OPTS=-Xms256m -Xmx256m"
+      - DISABLE_INSTALL_DEMO_CONFIG=true
+      - DISABLE_SECURITY_PLUGIN=true
+      - compatibility.override_main_response_version=true
+    ulimits:
+      memlock:
+        soft: -1
+        hard: -1
+    volumes:
+      - elasticsearch_data:/usr/share/elasticsearch/data
+    networks:
+      - mesh_network
+    healthcheck:
+      # URL must be quoted: an unquoted & backgrounds curl and the check
+      # always passes, letting Temporal start before OpenSearch is up.
+      test: ['CMD-SHELL', 'curl -f "http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=10s" || exit 1']
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+  temporal:
+    image: temporalio/auto-setup:1.28.1
+    depends_on:
+      database:
+        condition: service_healthy
+      elasticsearch:
+        condition: service_healthy
+    environment:
+      - DB=postgres12
+      - DB_PORT=5432
+      - POSTGRES_USER=postgres
+      - POSTGRES_PWD=postgres
+      - POSTGRES_SEEDS=database
+      - DYNAMIC_CONFIG_FILE_PATH=/etc/temporal/config/dynamicconfig/local.yaml
+      - TEMPORAL_ADDRESS=temporal:7233
+      - TEMPORAL_CLI_ADDRESS=temporal:7233
+      - ENABLE_ES=true
+      - ES_SEEDS=elasticsearch
+      - ES_PORT=9200
+      - ES_VERSION=v7
+      - ES_VIS_INDEX=temporal_visibility_v1_dev
+    ports:
+      - '7233:7233'
+    volumes:
+      # Mount ONLY the dynamic config — mounting over /etc/temporal/config
+      # would clobber the auto-setup image's config_template.yaml.
+      - ./temporal/local.yaml:/etc/temporal/config/dynamicconfig/local.yaml
+    networks:
+      - mesh_network
+
+  temporal-admin-tools:
+    image: temporalio/admin-tools:1.13.4
+    depends_on:
+      - temporal
+    environment:
+      - TEMPORAL_ADDRESS=temporal:7233
+      - TEMPORAL_CLI_ADDRESS=temporal:7233
+    networks:
+      - mesh_network
+    stdin_open: true
+    tty: true
+
+  temporal-ui:
+    image: temporalio/ui:2.16.2
+    depends_on:
+      - temporal
+    environment:
+      - TEMPORAL_ADDRESS=temporal:7233
+      - TEMPORAL_CORS_ORIGINS=http://localhost:3000,http://localhost:8233,http://localhost:8080
+      # Land on the seeded local tenant namespace ({tenant}-{env}).
+      - TEMPORAL_DEFAULT_NAMESPACE=local-dev
+      # Auth comes back with the seeded local Zitadel (mesh start seeds an
+      # org + CLI app + test users in a follow-up; until then the UI is open).
+      - TEMPORAL_AUTH_ENABLED=false
+    ports:
+      # 8233 = Temporal's conventional dev-UI port. Deliberately NOT 8081:
+      # the legacy tools/local stack serves its UI there, and a shared origin
+      # means shared browser localStorage — the UI would auto-redirect to
+      # namespaces remembered from the old stack ("namespace not found").
+      - '8233:8080'
+    networks:
+      - mesh_network
+
+  # Zitadel Database
+  zitadel-db:
+    image: postgres:17@sha256:a426e44bac0b759c95894d68e1a0ac03ecc20b619f498a91aae373bf06d8508d
+    ports:
+      - '127.0.0.1:5435:5432'
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: zitadel
+    volumes:
+      - zitadel_postgres_data:/var/lib/postgresql/data
+    networks:
+      - mesh_network
+    healthcheck:
+      # -h 127.0.0.1 (TCP) so the socket-only initdb-phase server can't
+      # satisfy the probe before first-boot init completes.
+      test: ['CMD-SHELL', 'pg_isready -h 127.0.0.1 -d zitadel -U postgres']
+      interval: '10s'
+      timeout: '30s'
+      retries: 5
+      start_period: '20s'
+
+  # One-shot: the machinekey volume must be writable by the zitadel user
+  # (uid 1000 — the image runs non-root and a fresh named volume is
+  # root-owned; the first-instance PAT write fails otherwise).
+  zitadel-machinekey-init:
+    image: busybox:1.36
+    command: chown -R 1000:1000 /machinekey
+    restart: 'no'
+    volumes:
+      - zitadel_machinekey:/machinekey
+    networks:
+      - mesh_network
+
+  # Zitadel Identity Server — v4 to match the cloud (approved tenant-auth
+  # pattern spec item 7: v4's no-role-claims machine tokens make version
+  # parity matter for auth testing).
+  zitadel:
+    image: ghcr.io/zitadel/zitadel:v4.15.3
+    depends_on:
+      zitadel-db:
+        condition: 'service_healthy'
+      zitadel-machinekey-init:
+        condition: 'service_completed_successfully'
+    ports:
+      - '127.0.0.1:8080:8080'
+    environment:
+      ZITADEL_DATABASE_POSTGRES_HOST: zitadel-db
+      ZITADEL_DATABASE_POSTGRES_PORT: 5432
+      ZITADEL_DATABASE_POSTGRES_DATABASE: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_USERNAME: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE: disable
+      ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME: postgres
+      ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD: postgres
+      ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE: disable
+      ZITADEL_EXTERNALSECURE: false
+      ZITADEL_EXTERNALDOMAIN: localhost
+      ZITADEL_EXTERNALPORT: 8080
+      ZITADEL_HTTP_CORS_ALLOWORIGIN: "*"
+      ZITADEL_HTTP_CORS_ALLOWHEADERS: "*"
+      ZITADEL_HTTP_CORS_ALLOWMETHODS: "*"
+      ZITADEL_HTTP_CORS_ALLOWCREDENTIALS: true
+      ZITADEL_HTTP_CSRF_DISABLED: true
+      # v4 defaults new instances to the login-v2 UI, which is a SEPARATE
+      # container this stack doesn't run — without this, the authorize flow
+      # redirects to /ui/v2/login and dead-ends. Keep the built-in v1 login.
+      # (The seeder also flips the instance feature via API, belt-and-braces.)
+      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: false
+      # Platform org (approved Zitadel tenant-auth pattern): `mesh` is the
+      # home of platform-layer creds (mesh-cli project, test users; Hub when
+      # its images land) — same org name as the cloud platform tenant. App
+      # tenants get their own orgs, auto-created by `mesh dev --local`
+      # (ZitadelTenantIdentity parity); an app with no `mesh:tenant` config
+      # lands in the default app-tenant org `local`.
+      ZITADEL_FIRSTINSTANCE_ORG_NAME: mesh
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: admin@local.mesh
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: LocalDev1!
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false
+      # Bootstrap machine user for the `mesh start` seeder: its PAT lands on
+      # the machinekey volume and the CLI reads it (docker compose cp) to
+      # create the Platform project, Mesh CLI OIDC app, and test users.
+      # First-instance settings only apply on the FIRST init — a pre-existing
+      # zitadel volume needs `mesh stop --destroy` to pick this up.
+      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME: local-seeder
+      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME: Local Seeder
+      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PAT_EXPIRATIONDATE: '2099-01-01T00:00:00Z'
+      ZITADEL_FIRSTINSTANCE_PATPATH: /machinekey/pat.txt
+    command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled --init-projections=true'
+    volumes:
+      - zitadel_machinekey:/machinekey
+    networks:
+      - mesh_network
+
+  # SpiceDB migration (runs to completion before spicedb serves)
+  spicedb-migrate:
+    image: authzed/spicedb:v1.42.1
+    command: datastore migrate head
+    restart: 'no'
+    depends_on:
+      database:
+        condition: service_healthy
+    environment:
+      SPICEDB_DATASTORE_ENGINE: postgres
+      SPICEDB_DATASTORE_CONN_URI: postgres://postgres:postgres@database:5432/spicedb?sslmode=disable
+    networks:
+      - mesh_network
+
+  # SpiceDB authorization engine
+  spicedb:
+    image: authzed/spicedb:v1.42.1
+    command: serve
+    depends_on:
+      spicedb-migrate:
+        condition: service_completed_successfully
+    environment:
+      SPICEDB_GRPC_PRESHARED_KEY: local-dev-key
+      SPICEDB_DATASTORE_ENGINE: postgres
+      SPICEDB_DATASTORE_CONN_URI: postgres://postgres:postgres@database:5432/spicedb?sslmode=disable
+      SPICEDB_HTTP_ENABLED: true
+    ports:
+      - '127.0.0.1:50051:50051'
+      - '127.0.0.1:8443:8443'
+    networks:
+      - mesh_network
+    healthcheck:
+      test: ['CMD', 'grpc_health_probe', '-addr=localhost:50051']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+  # ministack — the local AWS fabric (SSM Parameter Store + Secrets Manager +
+  # S3, all services on one port). MIT-licensed LocalStack replacement (design
+  # §2.5). Point AWS SDK clients at it via AWS_ENDPOINT_URL=http://localhost:4566.
+  #
+  # State persists across restarts (PERSIST_STATE saves to the volume on
+  # graceful shutdown, reloads on boot): the registry and app secrets that
+  # `mesh dev` provisions live ONLY here, so without this a Docker Desktop
+  # restart silently wiped every provisioned app while its services kept
+  # running stale. `mesh start` still re-seeds platform state idempotently;
+  # `mesh stop --destroy` removes the volume like every other data volume.
+  ministack:
+    image: ministackorg/ministack:1.4.1
+    ports:
+      - '127.0.0.1:4566:4566'
+    environment:
+      MINISTACK_REGION: us-east-2
+      PERSIST_STATE: '1'
+      STATE_DIR: /var/lib/ministack-state
+    volumes:
+      - ministack_state:/var/lib/ministack-state
+    networks:
+      - mesh_network
+    healthcheck:
+      # Pure-Python probe — the ministack image ships no curl/wget.
+      test: ['CMD', 'python', '-c', "import urllib.request; urllib.request.urlopen('http://localhost:4566/_ministack/health')"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 5s
+
+  # StackPort — local AWS console over the ministack fabric (MIT). Browse and
+  # inspect the registry (SSM), Secrets Manager, and S3 artifacts visually;
+  # E4's terminal complement until the local Hub lands. First consumer of the
+  # x-local-aws-env anchor. Host 4567 (container serves on 8080 = Zitadel's
+  # host port).
+  stackport:
+    image: davireis/stackport:0.3.4
+    ports:
+      - '127.0.0.1:4567:8080'
+    environment: *local-aws-env
+    depends_on:
+      ministack:
+        condition: service_healthy
+    networks:
+      - mesh_network
+
+  # ── Observability — the SAME backends the hosted platform runs ──────────
+  # OTel collector → Loki (logs, OTLP) + Tempo (traces, OTLP gRPC), Prometheus
+  # scraping the collector's metrics exporter. hub-api's LOKI_URL / TEMPO_URL /
+  # PROMETHEUS_URL point here, so the Hub's logs/traces/metrics views run the
+  # exact hosted code paths. `mesh dev --local` service logs are tailed from
+  # ${MESH_LOCAL_LOGS} (written via tmux pipe-pane) and labeled with the same
+  # k8s_namespace_name/k8s_deployment_name scheme the in-cluster
+  # k8sattributes processor produces.
+  loki:
+    image: grafana/loki:3.4.2
+    command: -config.file=/etc/loki/local-config.yaml
+    ports:
+      - '3100:3100'
+    volumes:
+      # The image's default local-config keeps all state under /tmp/loki.
+      - loki_data:/tmp/loki
+    networks:
+      - mesh_network
+
+  tempo:
+    image: grafana/tempo:2.7.1
+    command: -config.file=/etc/tempo/tempo.yaml
+    ports:
+      - '3200:3200'
+    volumes:
+      - ./observability/tempo.yaml:/etc/tempo/tempo.yaml
+      - tempo_data:/var/tempo
+    networks:
+      - mesh_network
+
+  prometheus:
+    image: prom/prometheus:v3.2.1
+    ports:
+      - '9090:9090'
+    volumes:
+      - ./observability/prometheus.yml:/etc/prometheus/prometheus.yml
+      # External-service probe targets (blackbox file_sd) — written by
+      # `mesh dev --externals` / ExternalService wiring, same labels the hosted
+      # Probe CRs carry (type/tenant/env/app/external_service).
+      - ${MESH_LOCAL_PROBES:-/tmp/mesh-local/probes}:/etc/prometheus/probes
+      - prometheus_data:/prometheus
+    networks:
+      - mesh_network
+
+  # Blackbox exporter — the same prober the hosted monitoring stack runs for
+  # ExternalService health checks; Prometheus drives it via the
+  # external-services file_sd job.
+  blackbox-exporter:
+    image: prom/blackbox-exporter:v0.25.0
+    command: --config.file=/etc/blackbox/blackbox.yml
+    ports:
+      - '9115:9115'
+    networks:
+      - mesh_network
+    volumes:
+      # IPv4-pinned http_2xx/tcp_connect modules — host.docker.internal's
+      # IPv6 ULA is unreachable from the container network.
+      - ./observability/blackbox.yml:/etc/blackbox/blackbox.yml
+    extra_hosts:
+      # Probe targets run on the HOST (mesh dev services/mocks).
+      - 'host.docker.internal:host-gateway'
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.121.0
+    command: --config=/etc/otelcol/config.yaml
+    ports:
+      - '4317:4317' # OTLP gRPC (apps: OTEL_EXPORTER_OTLP_ENDPOINT)
+      - '4318:4318' # OTLP HTTP
+      - '13133:13133' # health_check extension (mesh status probe)
+    volumes:
+      - ./observability/otel-collector.yaml:/etc/otelcol/config.yaml
+      # mesh dev --local writes {namespace}/{service}.log here (the CLI passes
+      # MESH_LOCAL_LOGS on every compose call; the fallback keeps raw
+      # `docker compose` usable).
+      - ${MESH_LOCAL_LOGS:-/tmp/mesh-local/logs}:/var/log/mesh-apps:ro
+    depends_on:
+      - loki
+      - tempo
+    networks:
+      - mesh_network
+    healthcheck:
+      test: ['CMD', '/otelcol-contrib', '--version']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  postgres_data:
+    driver: local
+  ministack_state:
+    driver: local
+  elasticsearch_data:
+    driver: local
+  zitadel_postgres_data:
+    driver: local
+  zitadel_machinekey:
+    driver: local
+  loki_data:
+    driver: local
+  tempo_data:
+    driver: local
+  prometheus_data:
+    driver: local
+
+networks:
+  mesh_network:
+    driver: bridge

package/stack/hub/Dockerfile.api

@@ -0,0 +1,18 @@
+# Local Hub API — built from the published @mesh-tech/hub tarball (interim
+# until the hub pipeline publishes container images; design §11 risk).
+# Build context = the extracted tarball; the CodeArtifact token comes in as
+# a BuildKit secret so it never lands in a layer.
+FROM node:22-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3
+# socat backs the in-container http://localhost:8080 → zitadel loopback
+# forward (see CMD): Zitadel routes every request by Host header to the
+# instance whose domain is `localhost`, so the ONE issuer URL that tokens
+# carry must resolve inside this container too — same invariant as hosted,
+# where the public issuer URL is valid everywhere.
+RUN apt-get update && apt-get install -y --no-install-recommends socat && rm -rf /var/lib/apt/lists/*
+WORKDIR /hub/api
+COPY api/package.json ./package.json
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm install --omit=dev --no-audit --no-fund
+COPY api/dist ./dist
+ENV PORT=3002
+EXPOSE 3002
+CMD ["sh", "-c", "socat TCP-LISTEN:8080,bind=127.0.0.1,fork,reuseaddr TCP:zitadel:8080 & exec node dist/index.js"]

package/stack/hub/Dockerfile.auth

@@ -0,0 +1,10 @@
+# Local oauth2-proxy for the Hub UI — the hosted auth sidecar (same binary,
+# same version as Service.ts deploys) plus a loopback forward: Zitadel routes
+# every request by Host header, so the ONE issuer URL (http://localhost:8080)
+# must be reachable inside this container too. Public images only — no
+# registry auth needed.
+FROM quay.io/oauth2-proxy/oauth2-proxy:v7.7.1 AS proxy
+FROM alpine:3.21
+RUN apk add --no-cache socat ca-certificates
+COPY --from=proxy /bin/oauth2-proxy /bin/oauth2-proxy
+ENTRYPOINT ["/bin/sh", "-c", "socat TCP-LISTEN:8080,bind=127.0.0.1,fork,reuseaddr TCP:zitadel:8080 & exec /bin/oauth2-proxy \"$@\"", "--"]

package/stack/hub/Dockerfile.ui

@@ -0,0 +1,10 @@
+# Local Hub UI — React Router SSR server from the published @mesh-tech/hub
+# tarball (see Dockerfile.api for the interim-build rationale).
+FROM node:22-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3
+WORKDIR /hub/ui
+COPY ui/package.json ./package.json
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm install --omit=dev --no-audit --no-fund
+COPY ui/build ./build
+ENV PORT=9000
+EXPOSE 9000
+CMD ["node", "build/server.js", "./build/server/index.js"]

package/stack/init/01-databases.sql

@@ -0,0 +1,12 @@
+-- Databases provisioned on first boot of the `mesh start` postgres instance.
+-- (POSTGRES_DB already creates `temporal`; opensearch handles visibility.)
+
+-- Application database for `mesh dev` apps
+CREATE DATABASE app;
+
+-- SpiceDB datastore (migrated by the spicedb-migrate service)
+CREATE DATABASE spicedb;
+
+-- Hub database (permission metadata lives in SpiceDB *and* here — with this
+-- DB and the Hub running, apps deploy locally with no additional services)
+CREATE DATABASE hub;

package/stack/observability/blackbox.yml

@@ -0,0 +1,20 @@
+# NOTE: --config.file makes this file REPLACE the image's built-in module set,
+# so every module a probe can select must be defined here (a probe naming a
+# module that isn't in this file fails the scrape). Add new modules below.
+#
+# Local blackbox-exporter modules — same names the scrape config uses, with
+# IPv4 pinned: probe targets are host.docker.internal (mesh dev services /
+# mocks on the host), whose Docker-provided IPv6 ULA is unreachable from the
+# container network, so the default ip6-preferred resolution dials a dead
+# address and every probe reads down.
+modules:
+  http_2xx:
+    prober: http
+    http:
+      preferred_ip_protocol: ip4
+      ip_protocol_fallback: true
+  tcp_connect:
+    prober: tcp
+    tcp:
+      preferred_ip_protocol: ip4
+      ip_protocol_fallback: true