Skip to content
Processes

Processes

Containers in the dev stack (deployment/compose.dev.yaml), the database roles (infrastructure/postgres/roles.json), and the networks (deployment/networks.dev.json, same membership as the compose file).

Every service drops all capabilities, sets no-new-privileges, uses a read-only root and its image’s non-root user, and has memory, CPU and process limits. The edge adds NET_BIND_SERVICE. Secret files live outside the checkout; the compose secrets: block names them. docs/human/runbooks/dev-stack-secrets.md is the runbook.

Dev stack

web runs interfaces/web, the SvelteKit server; its UNSET_SERVICE is still http. No other interface is a service in this file.

ServiceImageUserNetworksDatabase role
postgresdeployment/images/postgres.Dockerfile999:999dbbootstrap superuser; init creates migrator and tap
migratedeployment/images/migrate.Dockerfile65532:65532dbmigrator on database unset; restart: "no"
pdsghcr.io/undefined6799/unset/pds (digest-pinned): the official 0.4.5051 image with its OAuth UI dist replaced (P2.24y)1000:1000edge, pds_egressits own volume, not our Postgres
edgedeployment/edge65532:65532edge, app, newt_edge 10.250.37.3none
webdeployment/images/node-app.Dockerfile65532:65532db, app, web_egressweb
newtdocker.io/fosrl/newt:1.20.0 (digest-pinned)65532:65532newt_egress, newt_edge 10.250.37.2none

Newt is Pangolin’s connector (ADR 0030). Under dev the edge publishes no port. PLC_URL on web is https://plc.directory (ADR 0022, decided (0001 log), acceptance pending).

deployment/compose.local.yaml is the throwaway stack on one machine. deployment/compose.local.test.ts holds it to the dev file. Differences that change this picture: no Newt; the edge publishes 127.0.0.1:80 and 127.0.0.1:443; web sets NETGUARD_INTERNAL_HOSTS from PDS_HOSTNAME; pds-token-reader is a tools profile service and up does not start it. The file header lists the rest.

Internal hosts

NETGUARD_INTERNAL_HOSTS names hosts inside the stack that must resolve only to private addresses (shared/config/netGuard.ts). ADR 0022 Decision 3 names our PDS as that one entry (decided (0001 log), acceptance pending). ADR 0031 Decision 3 drops the exception on staging: web reaches the PDS through public DNS, Pangolin, Newt and the edge. The two do not conflict. 0022 is the egress rule. 0031 is the accepted staging path, and local still sets the one entry.

EnvironmentNETGUARD_INTERNAL_HOSTS
localSet to our PDS (deployment/compose.local.yaml, ${PDS_HOSTNAME})
dev/stagingMust be absent. devTunnelProblems (deployment/preflight/checks/networks.ts) fails a service that names one. The dev compose file does not set the key. ADR 0031 Decision 3 drops the exception.
prodRequired and non-empty. The field rule fails when UNSET_ENV is prod and the list is empty (shared/config/netGuard.ts).

Networks

NetworkInternalMembersUse
dbyespostgres, migrate, webPostgres
appyesedge, webedge to web:8080
edgenopds, edgethe only network shared with the PDS HTTP port
pds_egressnopdsthe PDS’s way out
web_egressnowebweb’s way out
newt_edgeyes, 10.250.37.0/29newt .2, edge .3Newt to the edge
newt_egressnonewtNewt’s tunnel to Pangolin

web and the PDS share no network. Under dev the edge has no network aliases (deployment/compose.dev.test.ts, no_service_answers_for_the_app_or_pds_host). ADR 0031 Decision 3: web resolves the staging PDS through public DNS to Pangolin, then Newt and the edge.

Database roles

deployment/postgres/init/00-bootstrap.sh runs at initdb and creates migrator (login, owns database unset) and tap (login, owns database tap). Those two are not in roles.json. deployment/compose.local.yaml mounts ./postgres/init on postgres and nothing else there, the same init directory deployment/compose.dev.yaml and deployment/compose.dev.source.yaml mount. The phase-1 book still describes a local read-only init-local/ mount (docs/ai/book/phase-1.md, the P1.34d difference list and P1.34u). That passage is superseded by ADR 0022 and ADR 0023 (no PLC of our own; both decided (0001 log), acceptance pending). deployment/postgres/init-local/10-local-plc.sh still creates a plc role. None of the three compose files mounts it.

Migration infrastructure/postgres/migrations/0003_roles_and_grants.sql creates every roles.json role with no table privileges. infrastructure/postgres/roles.ts sets a password only when passwordFrom is a file name. A login role with passwordFrom: null gets no password from that sync.

RoleClassLoginConnectionsstatement_timeoutPassword file
webserviceyes402spg_web_password
apiserviceyes202spg_api_password
indexerserviceyes1010spg_indexer_password
adminserviceyes105snone
retentionjobyes260snone
mediaserviceyes102snone
reviewserviceyes410snone
review_egressserviceyes25snone
auditorjobyes260snone
backupjobyes20none
legal_hold_readergroupno—nonenone
audit_ownerownerno—nonenone

Every roster role gets idle_in_transaction_session_timeout=10s, lock_timeout=3s and an empty search_path (migration 0003). web is the only roster role with a running service in the dev stack. api and indexer have password files mounted on migrate for the sync; their processes are not in the compose file.

Interface processes not in Compose

interfaces/indexer and interfaces/pds-admin are not services in deployment/compose.dev.yaml. Both run in deployment/compose.dev.source.yaml and deployment/compose.local.yaml. The other processes in guideline §1 get their folder with their first route (decision 34).