compose/relay
Nicolas De Loof 5c666993e1
Some checks are pending
ci / validate (lint) (push) Waiting to run
ci / validate (relay-lint) (push) Waiting to run
ci / validate (relay-test) (push) Waiting to run
ci / validate (validate-docs) (push) Waiting to run
ci / validate (validate-go-mod) (push) Waiting to run
ci / validate (validate-headers) (push) Waiting to run
ci / validate (validate-mocks) (push) Waiting to run
ci / binary (push) Waiting to run
ci / binary-finalize (push) Blocked by required conditions
ci / bin-image-test (push) Waiting to run
ci / relay-image-test (push) Waiting to run
ci / test (push) Waiting to run
ci / e2e (plugin, oldstable, graphdriver) (push) Waiting to run
ci / e2e (standalone, oldstable, graphdriver) (push) Waiting to run
ci / e2e (plugin, stable, containerd) (push) Waiting to run
ci / e2e (plugin, stable, graphdriver) (push) Waiting to run
ci / e2e (standalone, stable, containerd) (push) Waiting to run
ci / e2e (standalone, stable, graphdriver) (push) Waiting to run
ci / coverage (push) Blocked by required conditions
ci / ci-ok (push) Blocked by required conditions
ci / release (push) Blocked by required conditions
merge / bin-image-prepare (push) Waiting to run
merge / bin-image (push) Blocked by required conditions
merge / relay-image (push) Waiting to run
merge / module-image (push) Waiting to run
Scorecards supply-chain security / Scorecards analysis (push) Waiting to run
zizmor / zizmor (push) Waiting to run
fix(relay): build the relay image like the compose binary
The relay image ran its Go toolchain stage on the target platform, so every
platform it ships for needed a golang:alpine image of its own. The
golang:1.27.4-alpine tag has no linux/riscv64 variant (1.26 had one), which
fails the riscv64 leg of relay-image and relay-image-test on main since the
move to Go 1.27.

Build it the way the compose binary is built: the toolchain runs on the build
platform, from the same pinned golang alpine image, and xx cross-compiles for
the target and checks that the result is static. No platform depends on what
the golang image publishes any more.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
2026-11-12 19:07:46 +01:00
..
.golangci.yml ci: lint, vet and test relay/ as its own module 2026-09-17 09:23:54 +02:00
Dockerfile fix(relay): build the relay image like the compose binary 2026-11-12 19:07:46 +01:00
go.mod feat(provider): publish-endpoint deploys a network relay for provider services 2026-09-16 17:03:23 +02:00
main.go ci: lint, vet and test relay/ as its own module 2026-09-17 09:23:54 +02:00
main_test.go test: remove timing assumptions from TestBuildTLS and the relay streaming test 2026-10-12 11:55:20 +02:00
README.md feat(provider): publish-endpoint deploys a network relay for provider services 2026-09-16 17:03:23 +02:00

compose-relay

compose-relay is the network gateway Docker Compose deploys in place of a provider-managed service, so the other services of the project reach the provider's resource at the compose-native address — http://<service>:<port> — even though that resource lives outside the compose network.

Why it exists

A service can delegate its implementation to an external provider:

services:
  web:
    build: .
    depends_on:
      - database

  database:
    provider:
      type: awesomecloud

The provider's resource (a cloud database, a sandbox, a host process, ...) is not a container on the project network: web cannot resolve database, and the resource's ports are typically published somewhere on the host, at addresses and port numbers the application does not know. Until now consumers had to read injected environment variables to locate it.

When the provider declares where each endpoint actually listens, with one publish-endpoint message per port:

{ "type": "publish-endpoint", "message": "5432=localhost:49152" }

Compose deploys this relay in place of the service. web then connects to database:5432 exactly as if the service were a regular container; the relay forwards the connection to the real endpoint.

How it runs

Compose creates the relay container from the published docker/compose-relay image (override with COMPOSE_RELAY_IMAGE, e.g. for air-gapped setups or local development) with:

  • the service's canonical container name (<project>-<service>-1) and a network alias set to the service name, on the networks of every service that depends on the provider service;

  • the standard compose labels, so label-driven commands (ps, logs, stop, down) treat it as the service — plus the com.docker.compose.relay label identifying its role. Its value is a hash of the routes, letting up keep an up-to-date relay and recreate a stale one. Commands that act on a service's process (exec, cp) refuse relay containers;

  • the routes as environment:

    RELAY_ROUTES=5432=localhost:49152[,<port>=<host>:<port>...]
    

The binary listens on every declared container port and forwards each connection to its endpoint. TCP only, with half-close propagation so protocols relying on EOF work through the relay. It is intentionally minimal: a static Go binary on a scratch image, no configuration reload — Compose recreates the relay when the published endpoints change.

Building

$ docker buildx bake relay-image