Adding a service to the stack
This is for something Bothy itself runs - a container in this repository's
compose files. For something you run in ~/projects, see
Declaring a project; the two are different mechanisms and mixing
them up double-counts everything.
The rule that comes first#
Access is IP:port. There is no name layer. A browser-facing service
publishes a host port and is reached at http://<node-ip>:<port>.
A Host() rule in Traefik will register happily and then match nothing,
forever, because there is no name for it to match on. That failure is silent:
the router appears in the router table, docker ps looks right, and the URL
simply never resolves. It is the single most expensive mistake available here.
A container a browser reaches#
Pick a free port, publish it, join devnet, and add it to just urls:
services:
myapp:
image: myorg/myapp
networks: [default, devnet] # BOTH - see the warning below
ports:
- "8099:8080" # HOST:CONTAINER. Check the port is free first.
labels:
# Optional. Discovery works with zero labels.
- dev.portal.name=My App
- dev.portal.desc=What it does.
networks:
devnet:
external: trueThen, in order:
| Step | Why |
|---|---|
Run just urls and docker ps --format '{{.Ports}}' before choosing the number |
Ports are a flat namespace with no allocator. This check is the cost of the model and there is no way around it |
Add the port to the urls recipe in the justfile |
just urls is the only inventory. A service missing from it is a service nobody finds |
| Give it a login | It is on the tailnet with nothing in front of it. Use the shared DEV_LOGIN_* credential from .env, the way Grafana, Prometheus and the rest do |
Do not write a Host() rule |
See above |
| Do not attach the SSO middlewares | They are defined and attached to nothing on purpose. Attaching one router at a time is a rollout plan, not a per-service decision |
A container nothing browses#
Publish nothing. Join devnet and let other containers reach it by service
name. This is the correct default for exporters and sidecars - oauth2-proxy
and every *-exporter do exactly this.
It is not the default for anything that holds power. bothy-files,
bothy-ops, bothy-socket-read and bothy-socket-write are each on a private
two-member network instead, because devnet holds every third-party image on the
box and a proxy with no authentication is protected by nothing else - see
SECURITY.md section 2.
This paragraph listed all four as examples to copy until 2026-09-23.
A database#
Bind loopback explicitly and route nothing:
ports:
- "127.0.0.1:5432:5432"Containers reach it by name over devnet; humans reach it over an SSH tunnel.
A bare 5432:5432 publishes it to the whole tailnet.
A host process#
Reach it on its own port - Tilt at <node-ip>:10350, and so on. There is no
routing to set up.
How the console finds it, with no list to maintain#
You do not register a service anywhere. Classification comes from where its compose file lives, which a container carries as a label:
| Where the compose file is | Filed as |
|---|---|
under apps/ in this repository - Bothy's own tiers |
infra |
| elsewhere in this repository | stack (edge is infra, by name - it is not under apps/) |
| anywhere else | project |
| missing entirely | unmanaged / infra |
Infra is a place on disk, not a list of names. It used to be five project
names in the source and the list had already gone stale. A name test is also
unsafe, because compose project names are global to the Docker daemon and belong
to whoever claimed one first - a checkout at ~/projects/portal was being
declared part of Bothy.
The polish labels#
Everything above works with zero labels. If the page ever needs a label to be correct, the defaults are wrong and the defaults are the bug.
| Label | Effect |
|---|---|
dev.portal.project |
display name for the whole compose project - one label fixes every breadcrumb, panel title and card |
dev.portal.name |
this service's display name |
dev.portal.icon |
emoji |
dev.portal.desc |
card body text |
dev.portal.group / .groupKind |
force which panel it lands in. Display only |
dev.portal.hidden=true |
drop from Services. Still listed in Ports and Routes |
dev.portal.path |
deep link, e.g. /targets |
dev.portal.order |
sort order within a panel |
dev.portal.group being display-only is load-bearing. Every node carries two
group fields: system is what a service is (derived, and no label can move
it), group is where it is shown. That separation is what lets you regroup
the page without 404-ing the bookmark somebody took of the old URL, or
reshuffling the accent colours - the colour is hashed from the identity, not
from the display group.
The checklist#
| A free port | checked against just urls and docker ps first |
Listed in just urls |
otherwise it is invisible |
On devnet |
as [default, devnet], so Prometheus and the console see it |
| A login | the shared DEV_LOGIN_* credential. Nothing else is guarding it |
| Loopback if it is a database | 127.0.0.1:PORT:PORT, never a bare PORT:PORT |
No Host() rule |
there is no name layer to match |
| No SSO middleware | defined, deliberately unattached |
| Verified | on its own port, checking the bytes as well as the status code |
That last line is not pedantry. The console answers every unrouted request
on port 80 with its own page, from any address - so a 200 from http://<node-ip>/
proves nothing about your service. Check the port you published, and check that
what came back is yours.
Related#
- Declaring a project - for things you run outside this repository
- The files you will actually edit - what applies a saved change, and when
- Monitoring - what a service on
devnetgets for free docs/ARCHITECTURE.md- the request path and the networks, in full