Networking

Every address a bench answers on, and who can reach each one.

Who this is for. Somebody who cannot reach a bench, or who is changing how
one is addressed.

Before you start. A bench has up to four addresses at once. They are not
alternatives. Each one exists for a different caller, and three of the four are
private.

The four addresses

benchpress/addressing.py builds all of them in one place, and the app renders
what it returns rather than assembling a URL from a port it declared itself.

The two ports are properties of the bench image, not settings. They are
constants in addressing.py.

When a bench has no tunnel address the same helpers fall back to the container's
bridge address. When base_domain is empty or localhost, the two public
addresses do not exist and the helpers return nothing.

Bench bridges

A bench container joins a BenchPress bridge network, never the control plane's
own network.

Bridge N is derived, not configured:

The third octet steps by 16 so every /20 starts on its own boundary. A later
scheme giving each node a /16 renumbers nothing.

Choosing a bridge is advisory. placement.pick_network names the lowest
index with room. It takes no lock, and the count can go stale between the count
and the create. Docker is the arbiter. It refuses the create when the address
pool is empty, and the deploy rolls on to the next bridge.

A bridge is created when a bench actually reaches it. A Draft bench that is
never deployed costs no network.

Three infrastructure containers are attached to every bench bridge, so Docker's
embedded DNS answers in both directions: Traefik, the shared MariaDB and the
shared Redis. The control plane's own database and Redis are deliberately
absent. A tenant bridge that reaches them is a breach, not a convenience.

The WireGuard plane

Every bench and every user device is a VPN Peer in the vpn_management app.
benchpress/vpn_adapter.py is the only seam between the two apps.

The insert claims the tunnel address atomically from the server's pool. Nothing
picks an address by hand.

A bench peer keeps a 25 second keepalive. A device peer is named
[Type] Name, which is how the adapter tells devices from bench containers in
one peer table.

Seven device types are accepted: Mobile, Laptop, Desktop, Tablet, Server, IoT
and Embedded. get_device_types returns the list so no screen hand-types it.

A bench created before the bridge families existed falls back to the legacy
gateway 172.30.0.1.

The public front door

benchpress/ingress.py owns every write to the Traefik route directory, and
that directory path lives in that module and nowhere else.

Traefik's file provider does not recurse, so the directory is flat. One file
holds one router for one bench, named by the instance id, which is always 32
hexadecimal characters.

Two files in that directory are never a bench's, and the convergence pass must
never delete them. They are named one by one rather than matched by shape.

A route file names the container, never an address. The container name is
the instance id, so no lifecycle transition can make the file stale.

Why bench routers name no certificate resolver

A bench router is written with tls: {}. That turns TLS on and names no
resolver, so the router serves whatever certificate the store already holds for
the requested name.

This is the point of the design. Let's Encrypt allows five certificates for each
identifier set every seven days. A router that asked for its own certificate
would cap bench churn at five a week.

ensure_anchor is what puts *.<base domain> in the store, and it is the only
place in this app that names a resolver. The anchor is written at deploy step 1,
minutes ahead of the image build, because DNS-01 has to finish issuing before a
bench route goes live.

The anchor is never deleted at teardown. It has to outlive every bench, because
it is what keeps the certificate renewing.

The IDE hostname is one label under the same base domain, so the same wildcard
covers it. Only the site hostname is checked when a deploy logs the certificate
state.

Who can reach what

No bench is on the public internet by port. The only public path is Traefik, and
it terminates TLS on the wildcard.

Verify

Read what a bench answers on:

bench --site <site> execute frappe.client.get_value \
  --kwargs "{'doctype':'Bench Instance','filters':{'name':'<id>'},'fieldname':['public_url','code_server_url','wg_ip','container_ip','bridge_network']}"

List the bridges Docker actually has:

docker network ls --filter name=benchpress-

Troubleshooting

Reference

Related

• WireGuard and the VPN plane — standing the tunnel up.
• Deploy pipeline — the steps that produce these addresses.
• Open your site — the same addresses, from a user's side.
• Data model — why there is no Device DocType.