The files you will actually edit

Bothy is a set of Docker Compose stacks, a Traefik file-provider directory, two policy files and one .env. This page maps "I want to change X" onto the file that decides it, and says what has to happen before the change is live - because in nearly every case here, saving the file is not applying it.

The reasoning for individual settings lives in the compose files themselves. Every non-obvious line in them carries a comment explaining what broke without it, and those comments are the primary source. This page is the index.

The rule that comes first#

Use just. The justfile does set dotenv-load, so recipes see the root .env. docker compose looks for a .env beside the compose file it was handed, finds none, and either falls back to an insecure default or aborts on a required variable. Every group has a recipe:

Recipe Compose file
just up-edge edge/compose.yml
just up-data data/postgres/compose.yml
just up-auth auth/compose.yml
just up-monitoring monitoring/compose.yml
just up-apps apps/bothy/compose.yml, plus the cluster overlay when thales-scc exists

apps/bothy/compose.yml is a stub that pulls four fragments together with include: - the web tier (bothy-web), the files tier (bothy-files, which absorbed the config forms in 2026-09), the ops tier (bothy-ops, which absorbed the control and cluster tiers in the same consolidation) and the socket proxy. It is include: and not repeated -f for a specific reason worth knowing before you reach for the shorter form: with repeated -f, every relative path in every file resolves against the first file's directory. That built the editor tier from the web tier's Dockerfile, so bothy-files came up as nginx and crash-looped, and its audit-log bind mount silently moved somewhere nothing looks.

.env#

One file, gitignored, and the only place several values exist on earth. The comments in .env.example are the reference; these are the keys people actually go looking for.

Key What it decides
BOX_IP the address this box answers on. Read directly by auth/compose.yml in five places - Keycloak's hostname, the realm's redirect URI, the OIDC issuer, oauth2-proxy's redirect and its cookie whitelist
DEV_LOGIN_USER / DEV_LOGIN_PASSWORD the one shared credential every service with a native login uses, and the Keycloak admin password
NOTES_ROOT, PROJECTS_ROOT, HOME_ROOT, STATE_ROOT where the four things that live outside the repository are. Every one has a default; set one only if your layout differs
PUID / PGID who the three writing services run as. Left blank on purpose - just bootstrap fills them in from your own uid

Two things about BOX_IP that cost time if you learn them the hard way. It is the value most likely to be wrong in a way nothing reports: Keycloak advertises whatever it is told, oauth2-proxy independently validates that issuer, and if the two disagree by so much as a port the symptom is an infinite redirect loop, not an error. And nothing in .env is live until the stack that reads it is brought up again - for this key specifically, just up-auth.

Never write a second spelling of that address. The internal shortcut http://keycloak:8080 is deliberately unused in the OIDC configuration, because a second spelling is the bug.

Compose: adding a service#

The whole recipe, for the overwhelmingly common case:

  1. add the service to a compose file, or give it one of its own;
  2. publish a host port - there is no name layer, so this is how it is reached;
  3. put it on [default, devnet];
  4. add it to just urls, which is a human-maintained list and not a registry;
  5. docker compose -f <file> up -d, then confirm on http://<node-ip>/ that Bothy noticed it.

That last step is the test of the whole design: start any container and it appears on the Overview within ten seconds with no edit to Bothy. If it does not appear, the problem is the container, not the console.

Pick a free port with care. just urls lists the stack's ports; a project's claims live in its own manifest and nothing reconciles the two. Keycloak was once published on a port a stopped project had already declared - the collector TCP-probed the declared port, found something listening, and reported a service nobody had started as up. Check ss -ltn and the project manifests.

The full checklist, including the cases for a container nothing browses, a host process and a database, is docs/ARCHITECTURE.md § 7.

edge/dynamic/ - the Traefik file provider#

Traefik watches this directory and merges every .yml in it into one namespace. That single fact explains most of the shape of what is in there.

What is committed:

File What it declares
bothy-api.yml the portal's read-only data plane. The security boundary - read it in full before touching it
auth.yml the sso and sso-errors middlewares, and the host-less /oauth2/ router that makes the login flow reachable at all
bothy-gates.yml the ONLY definitions of the sso-viewer, sso-editor and sso-operator role gates. Every router file borrows them; deleting this file errors every gated router
bothy-files.yml four role-gated routers for the file tier
bothy-config.yml two role-gated routers for the config forms, served by bothy-files
bothy-admin.yml four role-gated routers for the admin reads - audit log, backups, credentials, users (operator)
bothy-ops.yml generated. 33 role-gated routers on bothy-ops: one per container verb, one per cluster action in apps/bothy-ops/catalog.toml, operator for a change and viewer for a read. Edit the catalog and run just ops-wiring; never edit this file
bothy-updates.yml five role-gated routers for the updates tier - operator to request or pause, viewer to read state
project.example.yml the annotated template, entirely commented out
bothy-prom.example.yml the template for the generated Prometheus route

bothy-prom.yml itself is gitignored and generated by just bothy-prom-route, because it carries the basic-auth header the edge injects on the portal's behalf.

Why there are zero Host() rules#

The .test name layer was retired on 2026-08-12 - deleted, not dormant. A Host() rule written today registers with status enabled and then matches nothing, forever. just verify asserts the count of them is zero, and that zero is the invariant; the total number of routers moves as tiers are added.

If a route is genuinely needed, the only shape that still works is a host-less exact Path() rule. Be aware of what that means: with no host to scope it, the route answers on every address this box has at once, in a shared global path namespace - so a generic path like /api will collide with the next project that wants /api. Prefix it with something unmistakably yours. edge/dynamic/project.example.yml is the template, and it is commented out on purpose: the file provider merges everything here, so an example with live YAML is not an example, it is configuration. That is not hypothetical - an example file once declared the same router and middleware names as a real generated file, and the merge silently replaced a live credential with the example's placeholder. Every request 401'd while the router still reported "enabled".

Path(), never PathPrefix()#

Every rule in the tiers that can change something is an exact Path(), with the variable part in the query string or the JSON body. This is a security control and not a style preference: a prefix rule covers every endpoint the service grows later, including one nobody meant to expose. With exact paths a new endpoint is unreachable until somebody edits a rule here, which is the correct default for services holding write handles on two git repositories and a path to the Docker daemon.

The trap that voids a whole file#

And one more that is not a syntax error at all:

Attaching a login to a router#

Add both middlewares, in this order: sso-errors@file, then sso@file. Reversed, a signed-out user gets a blank 401 instead of a sign-in page - the request passes through sso-errors on the way in and the 401 travels back out through it.

sso fails closed. If oauth2-proxy is down, every router carrying it returns 500 to everyone. That is correct for an auth boundary and it is precisely why you do not attach it to the thing you would need in order to fix it.

Which role a router requires lives in the middleware, not the service: sso-viewer, sso-editor and sso-operator are identical but for one word in a query string. Adding a tier is four lines of YAML, not another container. See Roles.

The dev.portal.* labels#

Everything on the Overview works with zero labels. If the page ever needs a label to be correct, the defaults are wrong. The labels are polish, read in apps/bothy-web/web/src/lib/discover.ts:

Label Effect
dev.portal.project display name for a whole compose project - one label fixes every breadcrumb and panel title
dev.portal.name this service's display name
dev.portal.icon an emoji
dev.portal.desc the card's body text
dev.portal.group, dev.portal.groupKind force which panel it lands in. Display only - what a service is cannot be moved by a label, so its accent colour and its old URL are unaffected
dev.portal.section, dev.portal.subgroup which Overview section (bothy, projects, or any name) and subgroup (core, helpers, ...) the system is shown under. apps/portal-collector/placement.yml overrides these; with neither, Bothy's own tiers go to Bothy › Core, shared stack services to Bothy › Helpers, everything else to Projects
dev.portal.hidden=true drop it from Services. Still listed under Ports and Routes
dev.portal.path a deep link, such as /targets
dev.portal.order sort order within a panel

dev.portal.project on any container in a project names the whole project, which is how Edge · Traefik and Identity · Keycloak get their titles. The naming form is Role · Vendor, and the argument for it is in edge/compose.yml beside the label: the Bothy prefix is earned by authorship, not proximity. Traefik is not "Bothy Edge" - if it breaks at 03:00 it is not Bothy's documentation you open.

Labels are fixed at container creation. Editing one and running docker restart does nothing; the container has to be recreated.

The two policy.toml files#

Both are access policy expressed as data rather than as constants in Python, both are read once at startup, and both fail closed - a missing file, a parse error, or a declared root that does not exist stops the service starting. There is no permissive fallback, because the only safe default is "nothing" and a service that serves nothing looks broken in a way people work around.

apps/bothy-files/policy.toml governs Bothy Files: which roots exist and which are writable, which directories are never served at any depth, which files are labelled sensitive, how many undo snapshots are kept, and what warning a given path shows before you overwrite it. It is itself editable through the explorer, and marked critical for the reason above - a bad edit here does not produce a permissive service, it produces one that will not come back until somebody repairs it from a shell on the box. See Bothy Files.

The [config] section of apps/bothy-files/policy.toml governs the settings forms (a separate apps/bothy-config/policy.toml until 2026-09): one root, YAML files only, and a named allowlist of fields a form may patch. .toml is deliberately absent from its suffixes, so the file declaring what may be written cannot be rewritten through the API it declares. It is a much smaller surface than the file tier on purpose - a form that could set volumes, privileged, command or network_mode would be arbitrary code on the box, and those are edited as a diff by somebody who has read the comment above them.

After you save, what actually applies it#

You changed Live when
edge/dynamic/*.yml immediately - Traefik watches the directory. Unless the mount is stale after a checkout
a compose labels: or ports: entry after docker compose -f <file> up -d recreates the container. A restart is not enough
.env after the stack that reads it is brought up again
a policy.toml after that service restarts. If it will not start, the policy is why
a theme under apps/bothy-web/data/themes/ on reload. Anything under web/src/ needs a rebuild

Then:

just verify     # 23 checks against the running edge, asserting on content
just doctor     # containers, Prometheus targets, disk, backup freshness

Next#