Networks

Databases in Docker usually listen only on their Compose project’s network, with no published port. To reach one, Wharfbase joins that network, the way another service of the project would. It only joins; it never changes the network or the other containers.

Attach modes

Settings → Discovery, or WB_NETWORK_ATTACH (the installer’s --no-network-attach sets off):

Mode	What happens
Auto (default)	Wharfbase joins the networks it needs, as few as possible to reach every database it found. Networks it joined but no activated database has used for 30 minutes are left again (WB_NETWORK_DETACH_UNUSED).
Ask	Nothing is joined by itself. Databases that need a network say so (needs network), and Join network on the database joins it. Networks already joined are kept.
Relays	Wharfbase joins no database network. For each database that needs one, it starts a relay: a small container of its own image that joins the database’s network and wharfbase_relay, and forwards the database’s port. Wharfbase joins only wharfbase_relay. See Relays.
Off	Wharfbase never joins a network. It reaches databases through published ports or the host only; others stay unreachable.

Every join and leave is in the audit log, with the databases it was for. After an upgrade recreates the Wharfbase container, the networks it had joined are joined again.

Relays

Joining a network lets Wharfbase reach every container on it, not only the database. With Relays, it reaches one port per database, through a container that does nothing else:

• The relay: Wharfbase’s own image running wharfbase relay --to <database>:<port>. It runs as a non-root user with a read-only filesystem, no capabilities and 64 MiB of memory, and is named wharfbase-relay-<container>-<port>-<instance>.
• Its networks: the database’s network and wharfbase_relay, an internal network that only Wharfbase and its relays share.
• Its lifetime: removed 30 minutes after its database is gone (with “Leave unused networks” on), and all relays are removed when you switch to another mode.
• Its owner: each relay carries the id of the Wharfbase that made it (wharfbase.relay.owner). With two Wharfbases on one Docker host, each starts, adopts and removes only its own relays.

Relays need the socket-guard to allow them: set WB_GUARD_ALLOW_RELAY=true in .env (it’s off by default), and WB_GUARD_ALLOW_NETWORK_ATTACH=false if Wharfbase should join nothing else. Then wharfbase up. The guard checks every relay: its image, command, user, limits and networks (socket-guard). Settings → Diagnostics says whether relays are allowed and how many are running.

Relays need Docker 25 or later, which can create a container on two networks at once.

Networks Wharfbase never joins

• The host and none networks.

• Swarm overlay networks that aren’t attachable.

• Any network labelled wharfbase.attach=false:

  networks:
    payments:
      labels:
        wharfbase.attach: 'false'

The socket-guard enforces the same rules, so Wharfbase can only ever connect and disconnect itself: never another container, and never a refused network.

When a database can’t be reached

The Reachability tab of each database lists every way Wharfbase could reach it: the container’s address on a shared network, a published port, or the host. For each one it shows whether it worked, and for the rest what’s missing. Common cases:

Shown	Why	What to do
needs network	Wharfbase isn’t on the database’s network: the attach mode is Ask or Off, or the network can’t be joined (labelled wharfbase.attach=false, or not attachable). In Relays mode: the guard doesn’t allow relays	Join network, or switch to Auto or Relays. For a network that can’t be joined, publish a port or remove the label. For relays, set WB_GUARD_ALLOW_RELAY=true
host config needed	A database on the host listens on 127.0.0.1 only	The tab shows the line to change (listen_addresses, bind-address, bind, net.bindIp)
Unreachable	Running, but nothing answered	The database is starting, or a firewall is in the way

Several servers (Pro): an agent on each server does the same there, so no network or port has to be opened between servers. See Multi-server.