@openmeet/snowglobe 0.0.0-stage → 0.3.0-rc.1

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@openmeet/snowglobe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0-rc.1",
+  "description": "Standalone, testable ATProto development network for local development and CI",
+  "type": "module",
+  "bin": {
+    "snowglobe": "bin/snowglobe.mjs"
+  },
+  "license": "MIT",
+  "author": "OpenMeet Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenMeet-Team/snowglobe.git"
+  },
+  "homepage": "https://snowglobe.at",
+  "keywords": [
+    "atproto",
+    "bluesky",
+    "pds",
+    "jetstream",
+    "docker",
+    "development",
+    "testing"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@atproto/api": "^0.15.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@peculiar/asn1-schema": "2.11.0",
+    "@peculiar/asn1-x509": "2.11.0",
+    "@peculiar/x509": "2.2.0",
+    "reflect-metadata": "0.2.2",
+    "yaml": "^2.9.1"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "stack/",
+    "!stack/**/*.test.mjs",
+    "snowglobe.default.yml",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/snowglobe.default.yml

@@ -0,0 +1,54 @@
+# The default snowglobe: one current PDS, a PLC directory and Jetstream, all at https names, with
+# Slingshot and PDSls (the record browser) beside them.
+# Copy this file to snowglobe.yml (here, or in your app's repo) and run bin/snowglobe.mjs up.
+# The commented sections below add more; docs/snowglobe.md says what each one does, and
+# docs/examples/atmo.yml is the whole thing: three PDSes, a relay and a lexicon authority.
+
+globe: snowglobe
+domain: local.snowglobe.at     # every name below is under it
+
+pds:
+  - name: main                 # https://main.local.snowglobe.at
+    image: ghcr.io/bluesky-social/pds:0.4.5037    # a current release
+    bare_handles: true         # its handles are <account>.local.snowglobe.at
+  # A second PDS, with handles <name>.other.local.snowglobe.at. With more than one PDS the
+  # relay turns on, so Jetstream sees every PDS's writes.
+  # - name: other
+  #   image: ghcr.io/bluesky-social/pds:0.4.5009
+  #
+  # The permissioned-spaces alpha. Invites are required, and it is the PDS to name as the
+  # lexicon authority below. Its short name is pinned by digest.
+  # - name: alpha
+  #   image: spaces-alpha
+  #   invites: required
+
+services:                      # these are the defaults, each true or false
+  jetstream: true
+  slingshot: true              # answers a handle's DID and PDS inside the network; needs jetstream
+  pdsls: true                  # https://pdsls.local.snowglobe.at, a browser for the network's records
+  tap: false                   # sends an app the events of one collection (true, or a map; see docs/snowglobe.md)
+  # relay: auto                # auto: on when there is more than one PDS
+
+# Where every PDS resolves lexicons (NSIDs) from. Name a PDS that is in this file.
+# lexicons:
+#   authority: alpha
+#   publish: lexicons          # a folder next to this file; up publishes every lexicon in it
+
+# A group host runs beside the PDSes, at https://gh.local.snowglobe.at.
+# grouphosts:
+#   - name: gh
+#     kind: opensocial
+#     build: ../atproto-group-host   # a folder with a Dockerfile, from this file's folder
+
+accounts:                      # <name>@<pds>; up makes each one
+  - alice@main
+  - bob@main
+
+# Your app, reached at https://myapp.app.local.snowglobe.at, with settings from the snowglobe.
+# `snowglobe env` hands them over; docs/your-app.md has the names.
+# apps:
+#   - name: myapp
+#     local: { port: 5173 }
+#     env:
+#       PUBLIC_ATPROTO_PLC_URL: ${services.plc.url}
+#       PUBLIC_ATPROTO_SIGNUP_PDS: ${pds.main.url}

package/stack/docker-compose.relay.yml

@@ -0,0 +1,105 @@
+# A local relay that crawls every PDS, so Jetstream and TAP see one merged stream, as they would
+# in production. Read by lib/render.mjs when the relay is on; not meant to be run directly (see
+# docker-compose.yml).
+#
+#   PDSes --> relay (:2470) --> Jetstream (:6008)
+#                          \--> TAP (:2480)
+#
+# The relay joins the PDSes' network namespace: it connects to each host at the
+# localhost URL in its accounts' DID documents, and checks that each account's DID
+# document names the host the event came from. TAP joins too, because a backfill
+# fetches repos from those same URLs. Jetstream only reads the relay, so it stays
+# on the bridge network and reaches the relay as pds:2470.
+#
+# A relay only adds localhost hosts through its admin API, so a PDS cannot register
+# itself with requestCrawl. relay-init adds each PDS once the relay is up.
+
+x-relay-admin-password: &relay-admin-password ${SG_RELAY_ADMIN_PASSWORD:?snowglobe up makes it}
+
+services:
+  pds:
+    ports: !override
+      - "${SG_SPACES_PDS_PORT:-${DEVNET_SPACES_PDS_PORT:-3010}}:${SG_SPACES_PDS_PORT:-${DEVNET_SPACES_PDS_PORT:-3010}}"
+      - "3020:3020"
+      - "3030:3030"
+      - "${SG_RELAY_PORT:-${DEVNET_RELAY_PORT:-2470}}:2470"
+      - "${SG_TAP_PORT:-${DEVNET_TAP_PORT:-2480}}:2480"
+
+  relay:
+    # Upstream's relay with one patch, so it can crawl PDSes on localhost; see
+    # relay/Dockerfile. SG_RELAY_INDIGO_COMMIT picks the indigo commit (it needs
+    # a published relay-<commit> image, and the patch has to apply).
+    build:
+      context: ./stack/relay
+      args:
+        INDIGO_COMMIT: ${SG_RELAY_INDIGO_COMMIT:-${DEVNET_RELAY_INDIGO_COMMIT:-b2619d864df00a66455bd9f5f0c83c1ac13ad73d}}
+    image: atproto-devnet-relay:${SG_RELAY_INDIGO_COMMIT:-${DEVNET_RELAY_INDIGO_COMMIT:-b2619d864df00a66455bd9f5f0c83c1ac13ad73d}}
+    restart: unless-stopped
+    network_mode: service:pds
+    depends_on:
+      pds:
+        condition: service_healthy
+    environment:
+      RELAY_ADMIN_PASSWORD: *relay-admin-password
+      RELAY_PLC_HOST: http://plc:2582
+      # ws:// hosts; localhost hosts are accepted only through the admin API
+      RELAY_ALLOW_INSECURE_HOSTS: "true"
+      # the patched host check (relay/allow-private-hosts.patch)
+      RELAY_ALLOW_PRIVATE_HOSTS: "true"
+      # the PDS builds differ in how much sync metadata their events carry
+      RELAY_LENIENT_SYNC_VALIDATION: "true"
+      ENVIRONMENT: dev
+    volumes:
+      - relay-data:/data/relay
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:2470/xrpc/_health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  relay-init:
+    image: alpine:3.20
+    network_mode: service:pds
+    depends_on:
+      relay:
+        condition: service_healthy
+      pds-regular:
+        condition: service_healthy
+      pds-prod:
+        condition: service_healthy
+    environment:
+      RELAY_ADMIN_PASSWORD: *relay-admin-password
+      RELAY_HOSTS: localhost:${SG_SPACES_PDS_PORT:-${DEVNET_SPACES_PDS_PORT:-3010}} localhost:3020 localhost:3030
+    entrypoint: /bin/sh
+    command:
+      - -c
+      - |
+        set -eu
+        apk add --no-cache curl >/dev/null 2>&1
+        for host in $$RELAY_HOSTS; do
+          echo "[relay-init] crawl $$host"
+          curl -sf -u "admin:$$RELAY_ADMIN_PASSWORD" -H "Content-Type: application/json" \
+            -d "{\"hostname\": \"$$host\"}" http://localhost:2470/admin/pds/requestCrawl
+          echo
+        done
+    restart: "no"
+
+  jetstream:
+    depends_on:
+      relay:
+        condition: service_healthy
+    environment:
+      JETSTREAM_WS_URL: ws://pds:2470/xrpc/com.atproto.sync.subscribeRepos
+
+  tap:
+    network_mode: service:pds
+    ports: !reset []
+    networks: !reset []
+    depends_on:
+      relay:
+        condition: service_healthy
+    environment:
+      TAP_RELAY_URL: http://localhost:2470
+
+volumes:
+  relay-data:

package/stack/docker-compose.test.yml

@@ -0,0 +1,41 @@
+# Postgres and MailDev, which the PLC server and the PDS's email verification need. Read by
+# lib/render.mjs; not meant to be run directly (see docker-compose.yml).
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    # PLC restarts on its own (unless-stopped) but needs this; without it a
+    # Docker restart leaves postgres down and PLC crash-looping on DNS.
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}
+      POSTGRES_PASSWORD: ${SG_DB_PASSWORD:?snowglobe up makes it}
+      POSTGRES_DB: ${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}
+    ports:
+      - "${SG_POSTGRES_PORT:-${DEVNET_POSTGRES_PORT:-5433}}:5432"
+    networks:
+      - atproto-devnet
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+
+  maildev:
+    image: maildev/maildev:latest
+    restart: unless-stopped
+    ports:
+      - "${SG_MAILDEV_WEB_PORT:-${DEVNET_MAILDEV_WEB_PORT:-1081}}:1080"
+      - "${SG_MAILDEV_SMTP_PORT:-${DEVNET_MAILDEV_SMTP_PORT:-1026}}:1025"
+    networks:
+      - atproto-devnet
+
+  # Override PLC/PDS to depend on test postgres/maildev
+  plc:
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  pds:
+    environment:
+      PDS_EMAIL_SMTP_URL: smtp://maildev:1025

package/stack/docker-compose.yml

@@ -0,0 +1,179 @@
+# The service definitions snowglobe starts from (lib/render.mjs reads this file and
+# docker-compose.test.yml and docker-compose.relay.yml, and writes the compose file a snowglobe
+# runs). Not meant to be run directly: its paths are relative to the repository root, so use
+# `bin/snowglobe.mjs up`.
+#
+# Needs from the rendered file: PostgreSQL (for the PLC server) and an SMTP server (for the
+# PDS's email verification), which docker-compose.test.yml supplies.
+
+services:
+  # ── DID Registry ─────────────────────────────────────────────────
+  plc:
+    image: itaru2622/bluesky-did-method-plc:latest
+    restart: unless-stopped
+    # PLC needs DB_CREDS_JSON as a JSON string, which can't be built from
+    # env var interpolation in compose. We wrap the entrypoint to construct
+    # it at runtime from the same credential vars used everywhere else. The container's own
+    # DEVNET_DB_* keep their names, though the settings are SG_DB_*: a project's overlay may set
+    # them on this service (openmeet-api's docker-compose-devnet.yml does).
+    entrypoint: >
+      sh -c "
+        export DB_CREDS_JSON=$$(printf '{\"username\":\"%s\",\"password\":\"%s\",\"host\":\"%s\",\"port\":\"%s\",\"database\":\"%s\"}' \"$$DEVNET_DB_USER\" \"$$DEVNET_DB_PASSWORD\" \"$$DEVNET_DB_HOST\" \"$$DEVNET_DB_PORT\" \"$$DEVNET_DB_NAME\")
+        export DB_MIGRATE_CREDS_JSON=$$DB_CREDS_JSON
+        exec node /app/packages/server/service/index.js
+      "
+    environment:
+      PORT: 2582
+      DEVNET_DB_USER: ${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}
+      DEVNET_DB_PASSWORD: ${SG_DB_PASSWORD:?snowglobe up makes it}
+      DEVNET_DB_HOST: ${SG_DB_HOST:-${DEVNET_DB_HOST:-postgres}}
+      DEVNET_DB_PORT: ${SG_DB_PORT:-${DEVNET_DB_PORT:-5432}}
+      DEVNET_DB_NAME: ${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}
+      DATABASE_URL: "postgres://${SG_DB_USER:-${DEVNET_DB_USER:-postgres}}:${SG_DB_PASSWORD:?snowglobe up makes it}@${SG_DB_HOST:-${DEVNET_DB_HOST:-postgres}}:${SG_DB_PORT:-${DEVNET_DB_PORT:-5432}}/${SG_DB_NAME:-${DEVNET_DB_NAME:-plc}}"
+      ENABLE_MIGRATIONS: "true"
+      LOG_ENABLED: "true"
+      LOG_LEVEL: info
+      NODE_ENV: development
+    ports:
+      - "${SG_PLC_PORT:-${DEVNET_PLC_PORT:-2582}}:2582"
+    networks:
+      - atproto-devnet
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:2582/_health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Personal Data Server ─────────────────────────────────────────
+  pds:
+    # Any PDS build: a release (ghcr.io/bluesky-social/pds:<version>) or an
+    # upstream commit (ghcr.io/bluesky-social/atproto:pds-<commit sha>).
+    image: ${SG_PDS_IMAGE:-${DEVNET_PDS_IMAGE:-ghcr.io/bluesky-social/pds:0.4}}
+    # Release images run as root; monorepo images run as `node`, which cannot
+    # open the root-owned pds-data volume.
+    user: root
+    restart: unless-stopped
+    depends_on:
+      plc:
+        condition: service_healthy
+    environment:
+      PDS_PORT: 3000
+      PDS_HOSTNAME: ${SG_PDS_HOSTNAME:-${DEVNET_PDS_HOSTNAME:-devnet.test}}
+      PDS_DATA_DIRECTORY: /pds/data
+      PDS_BLOBSTORE_DISK_LOCATION: /pds/data/blocks
+      PDS_DID_PLC_URL: http://plc:2582
+      # The PDS forwards app.bsky.* reads, and any XRPC method it does not implement
+      # (com.atproto.space.* on a build without spaces, for one), to this AppView with
+      # a service-auth token for the caller. The default host does not resolve, so
+      # nothing on this network reaches Bluesky's production AppView. Point it at a
+      # real AppView only if your app needs reads proxied through the PDS; Bluesky's
+      # AppView never sees devnet accounts, since no relay outside devnet crawls them.
+      PDS_BSKY_APP_VIEW_URL: ${SG_APPVIEW_URL:-${DEVNET_APPVIEW_URL:-https://appview.invalid}}
+      PDS_BSKY_APP_VIEW_DID: ${SG_APPVIEW_DID:-${DEVNET_APPVIEW_DID:-did:example:invalid}}
+      PDS_REPORT_SERVICE_URL: ${SG_REPORT_SERVICE_URL:-${DEVNET_REPORT_SERVICE_URL:-https://moderator.invalid}}
+      PDS_REPORT_SERVICE_DID: ${SG_REPORT_SERVICE_DID:-${DEVNET_REPORT_SERVICE_DID:-did:example:invalid}}
+      PDS_CRAWLERS: ""
+      # PDS builds after upstream 1ff43e6e5 (2026-09-10) resolve DIDs through the
+      # SSRF-protected fetch, which refuses the local PLC's http:// URL.
+      PDS_DISABLE_SSRF_PROTECTION: "true"
+      PDS_INVITE_REQUIRED: "true"
+      PDS_ADMIN_PASSWORD: ${SG_PDS_ADMIN_PASSWORD:?snowglobe up makes it}
+      PDS_JWT_SECRET: ${SG_PDS_JWT_SECRET:?snowglobe up makes it}
+      PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX: ${SG_PLC_ROTATION_KEY:?snowglobe up makes it}
+      PDS_EMAIL_SMTP_URL: ${SG_SMTP_URL:-${DEVNET_SMTP_URL:-smtp://maildev:1025}}
+      PDS_EMAIL_FROM_ADDRESS: noreply@devnet.test
+      PDS_HANDLE_DOMAINS: ${SG_HANDLE_DOMAIN:-${DEVNET_HANDLE_DOMAIN:-.devnet.test}}
+      PDS_SERVICE_HANDLE_DOMAINS: ${SG_HANDLE_DOMAIN:-${DEVNET_HANDLE_DOMAIN:-.devnet.test}}
+      LOG_ENABLED: "true"
+      NODE_ENV: development
+    volumes:
+      - pds-data:/pds/data
+    ports:
+      - "${SG_PDS_PORT:-${DEVNET_PDS_PORT:-3000}}:3000"
+    networks:
+      - atproto-devnet
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:3000/xrpc/_health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Jetstream (JSON event stream from PDS firehose) ──────────────
+  jetstream:
+    image: ghcr.io/bluesky-social/jetstream:sha-05c89f0
+    restart: unless-stopped
+    depends_on:
+      pds:
+        condition: service_healthy
+    environment:
+      JETSTREAM_WS_URL: ws://pds:3000/xrpc/com.atproto.sync.subscribeRepos
+      JETSTREAM_DATA_DIR: /data
+      JETSTREAM_LIVENESS_TTL: 86400s
+    volumes:
+      - jetstream-data:/data
+    ports:
+      - "${SG_JETSTREAM_PORT:-${DEVNET_JETSTREAM_PORT:-6008}}:6008"
+      - "${SG_JETSTREAM_METRICS_PORT:-${DEVNET_JETSTREAM_METRICS_PORT:-6009}}:6009"
+    networks:
+      - atproto-devnet
+    healthcheck:
+      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/127.0.0.1/6008'"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── TAP (repo sync + backfill) ───────────────────────────────────
+  tap:
+    # Pinned by digest (indigo revision 4f47add4, built 2026-03-11): the one the Statusphere flow was run against.
+    image: ghcr.io/bluesky-social/indigo/tap@sha256:5e20bfe416d29fcd215ed8bf99f10b2ab825a6de4e5599846dd33967ade2abeb
+    restart: unless-stopped
+    depends_on:
+      pds:
+        condition: service_healthy
+    environment:
+      TAP_RELAY_URL: http://pds:3000
+      TAP_PLC_URL: http://plc:2582
+      TAP_DATABASE_URL: sqlite:///data/tap.db
+      TAP_DISABLE_ACKS: "true"
+      TAP_LOG_LEVEL: info
+    volumes:
+      - tap-data:/data
+    ports:
+      - "${SG_TAP_PORT:-${DEVNET_TAP_PORT:-2480}}:2480"
+    networks:
+      - atproto-devnet
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:2480/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Init (one-shot setup) ────────────────────────────────────────
+  init:
+    image: alpine:3.20
+    depends_on:
+      pds:
+        condition: service_healthy
+      plc:
+        condition: service_healthy
+    volumes:
+      - ./stack/init:/scripts:ro
+      - ./data:/devnet-data
+    environment:
+      PDS_HOSTNAME: ${SG_PDS_HOSTNAME:-${DEVNET_PDS_HOSTNAME:-devnet.test}}
+      PDS_ADMIN_PASSWORD: ${SG_PDS_ADMIN_PASSWORD:?snowglobe up makes it}
+      HANDLE_DOMAIN: ${SG_HANDLE_DOMAIN:-${DEVNET_HANDLE_DOMAIN:-.devnet.test}}
+      SEED_ACCOUNTS: ${SG_SEED_ACCOUNTS:-${DEVNET_SEED_ACCOUNTS:-true}}
+    entrypoint: /bin/sh
+    command: ["/scripts/init.sh"]
+    networks:
+      - atproto-devnet
+    restart: "no"
+
+volumes:
+  pds-data:
+  jetstream-data:
+  tap-data:
+
+networks:
+  atproto-devnet:

package/stack/https/app-names.cjs

@@ -0,0 +1,31 @@
+// Preloaded into each PDS (NODE_OPTIONS=--require, in the globe bin/snowglobe.mjs render writes), so a PDS can
+// reach an app at https://<name>.app.<domain>: it fetches a confidential client's
+// metadata and keys from there. Docker's DNS has no wildcard names, so every such name is
+// looked up as nginx instead, which routes it by name (stack/https/nginx.conf.template). Only
+// the address lookup changes: the request still carries the app's name, and TLS still
+// checks the certificate for it against the snowglobe CA. Every other name resolves as usual.
+//
+// SG_RESOLVE_DOMAIN sets the domain whose names, itself included, go to nginx. Each PDS sets it
+// to app.<domain>, where the apps are; a group host sets it to the globe's domain: it resolves its members' handles, which Docker's DNS does
+// not know.
+'use strict';
+const dns = require('dns');
+
+// DEVNET_ was these settings' prefix until 2026-10-20; a container made before then still has it.
+const DOMAIN = (process.env.SG_RESOLVE_DOMAIN || process.env.DEVNET_RESOLVE_DOMAIN || '').toLowerCase();
+const PROXY = process.env.SG_APP_PROXY_HOST || process.env.DEVNET_APP_PROXY_HOST || 'nginx';
+const isApp = (name) => {
+  if (typeof name !== 'string') return false;
+  const n = name.toLowerCase().replace(/\.$/, '');
+  return DOMAIN !== '' && (n === DOMAIN || n.endsWith(`.${DOMAIN}`));
+};
+
+const lookup = dns.lookup;
+dns.lookup = function snowglobeLookup(hostname, ...rest) {
+  return lookup.call(this, isApp(hostname) ? PROXY : hostname, ...rest);
+};
+
+const lookupPromise = dns.promises.lookup;
+dns.promises.lookup = function snowglobeLookupPromise(hostname, ...rest) {
+  return lookupPromise.call(this, isApp(hostname) ? PROXY : hostname, ...rest);
+};

package/stack/https/dns/Dockerfile

@@ -0,0 +1,10 @@
+# The DNS a service in the compose network needs to check a handle: any name under
+# SG_DOMAIN answers nginx's address. Docker's own DNS answers the service names first
+# and asks this only for names it does not know; this refuses every name outside the domain,
+# so nothing on the public internet resolves.
+# On the machine the lab does this one name at a time (bin/snowglobe.mjs run); inside the
+# network there is no such thing, and a handle's name is made when its account is.
+FROM alpine:3.22
+RUN apk add --no-cache dnsmasq
+COPY dns.sh /dns.sh
+ENTRYPOINT ["/bin/sh", "/dns.sh"]

package/stack/https/dns/dns.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+# dnsmasq for the https snowglobe. Every name under $SG_DOMAIN answers nginx's address
+# (A only; other record types get no answer, and nothing under the domain is asked of any
+# other server). It is the container's `dns:` server, which Docker's embedded DNS asks for
+# any name it does not know itself, so service names keep working and nothing else is
+# answered here.
+# nginx's address changes when nginx is recreated, so it is looked up again every few
+# seconds and dnsmasq restarted when it moved.
+# When dnsmasq dies it is started again here, and this script does not exit: slingshot runs
+# in this container's network namespace, and restarting this container leaves slingshot
+# with no network at all until slingshot is recreated too.
+set -eu
+: "${SG_DOMAIN:?}"
+ip_of_nginx() { getent hosts nginx | awk 'NR == 1 { print $1 }'; }
+start() {
+  dnsmasq -k --no-resolv --no-hosts \
+    --local="/${SG_DOMAIN}/" --address="/${SG_DOMAIN}/$1" &
+  pid=$!
+}
+trap 'kill "${pid:-0}" 2>/dev/null; exit 0' TERM INT
+# With no address, --address would answer NXDOMAIN for the whole domain, so wait for one.
+ip=""
+until [ -n "${ip}" ]; do
+  ip=$(ip_of_nginx || true)
+  [ -n "${ip}" ] || sleep 1
+done
+start "${ip}"
+while sleep 5; do
+  now=$(ip_of_nginx || true)
+  if [ -n "${now}" ] && [ "${now}" != "${ip}" ]; then
+    kill "${pid}" 2>/dev/null || true
+    wait "${pid}" 2>/dev/null || true
+    ip="${now}"
+    start "${ip}"
+  elif ! kill -0 "${pid}" 2>/dev/null; then
+    echo "dns.sh: dnsmasq exited; starting it again" >&2
+    wait "${pid}" 2>/dev/null || true
+    start "${ip}"
+  fi
+done

package/stack/https/nginx.conf.template

@@ -0,0 +1,104 @@
+# nginx for the https snowglobe (the globe's compose.yml, bin/snowglobe.mjs render). One leaf
+# certificate names every host below; data/https/ca.crt is the CA that signed it (bin/snowglobe.mjs certs).
+# A template: at start the image writes it to conf.d/default.conf with the SG_DOMAIN
+# setting filled in, so this is the http block's whole server list. The comments below
+# name its default, local.snowglobe.at.
+
+# Docker's embedded DNS, re-asked every 10 s, so a recreated container's new
+# address is picked up without reloading nginx.
+resolver 127.0.0.11 valid=10s ipv6=off;
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+ssl_certificate     /etc/nginx/https/leaf.crt;
+ssl_certificate_key /etc/nginx/https/leaf.key;
+ssl_protocols       TLSv1.2 TLSv1.3;
+
+proxy_http_version 1.1;
+proxy_set_header Host $host;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto https;
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection $connection_upgrade;
+# Firehose and event-stream websockets stay open.
+proxy_read_timeout 1h;
+proxy_send_timeout 1h;
+# Blob uploads.
+client_max_body_size 100m;
+
+# A name this file does not list gets no certificate at all.
+server {
+    listen 443 ssl default_server;
+    ssl_reject_handshake on;
+}
+
+# Each PDS and its handles, and the relay, the feed, Slingshot and PDSls, at their names under
+# the domain: rendered from snowglobe.yml by bin/snowglobe.mjs render into the globe's nginx/
+# folder (data/globe/nginx/globe.conf), mounted at /etc/nginx/globe/. Each PDS is its own
+# service, pds-<name>:3000. A PDS answers /.well-known/atproto-did by Host, which the http block
+# passes through as sent. An app's handle ending (below) wins over a PDS's *.<domain> as the
+# longer wildcard.
+include /etc/nginx/globe/*.conf;
+
+# The directory at an https name under the domain, as a hosted globe has it (plc.<globe>), so an
+# app's browser code, which cannot use plain http or the host's ports, reaches it too.
+server {
+    listen 443 ssl;
+    server_name plc.${SG_DOMAIN};
+    location / {
+        set $plc http://plc:2582;
+        proxy_pass $plc;
+    }
+}
+
+# The network's own page at the bare name, as a globe serves it at <globe>.snowglobe.at: the same
+# page/index.html, with this stack's relays (page/snowglobe.conf) and a snowglobe.json naming its
+# services, which bin/snowglobe.mjs up and snowglobe app write.
+server {
+    listen 443 ssl;
+    server_name ${SG_DOMAIN};
+    server_tokens off;
+    root /srv/page;
+    include /etc/nginx/page/snowglobe.conf;
+}
+
+# This stack's PLC, standing in for the real directory.
+server {
+    listen 443 ssl;
+    server_name plc.directory;
+    location / {
+        set $plc http://plc:2582;
+        proxy_pass $plc;
+    }
+}
+
+# Apps on this machine: https://<name>.app.${SG_DOMAIN} goes to the port that
+# bin/snowglobe.mjs app recorded for <name> (data/https/apps). It writes, into
+# data/https/nginx/ (mounted at /etc/nginx/snowglobe/), one upstream per app, naming
+# host.docker.internal, and one map line per name. An upstream's name is resolved
+# once, when nginx loads it, through the container's hosts file (extra_hosts), which
+# Docker's DNS does not serve. Neither file has to exist. An app that claimed a handle
+# ending (bin/snowglobe.mjs app <name> <port> <ending>) also gets a server there for
+# *.<ending>.local.snowglobe.at, which wins over a PDS's *.local.snowglobe.at as the
+# longer wildcard.
+include /etc/nginx/snowglobe/*.conf;
+
+map $host $snowglobe_app {
+    default "";
+    include /etc/nginx/snowglobe/*.map;
+}
+
+# A name no app registered gets a 404 from nginx itself and reaches nothing.
+server {
+    listen 443 ssl;
+    server_name *.app.${SG_DOMAIN};
+    if ($snowglobe_app = "") {
+        return 404 "No app is registered at $host (bin/snowglobe.mjs app).\n";
+    }
+    location / {
+        proxy_pass http://$snowglobe_app;
+    }
+}

package/stack/https/proxy/Dockerfile

@@ -0,0 +1,8 @@
+# The snowglobe's way in for a browser on another computer (server.mjs): a proxy to nginx and
+# the PAC file that points at it, on one port. No dependencies, Node's own net and http.
+FROM node:22-alpine
+WORKDIR /app
+COPY server.mjs ./
+USER node
+EXPOSE 1080
+CMD ["node", "server.mjs"]