From 55ea071092fec2e0c4d9d23f29ec59eb370e8f1b Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 04:09:16 +1000 Subject: [PATCH] docs: drop one host's service names from port guidance Five files named a specific host's service and the port it holds as the reason a deployment might move the state store's listen address, including config.example.toml, which ships to every operator. The guidance keeps its point -- move the listen/target pair together when a port is already taken on the host -- without naming a service the reader may not run, or have heard of. Also corrects the Taskfile's dev-stack summary, which still described the state store as binding 127.0.0.1:9090. deployments/dev.toml pairs it with 9091, and has since the pair became configurable, so the comment described a stack that does not start. --- Taskfile.yml | 8 ++++---- cmd/archie-state-store/main_test.go | 4 ++-- config.example.toml | 4 ++-- deployments/dev.toml | 2 +- internal/app/archied/listen.go | 4 ++-- internal/infrastructure/configuration/services_test.go | 4 ++-- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 11a6c66b2..4c4c246a8 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -274,7 +274,7 @@ tasks: * air rebuilds and restarts archied on Go changes * archie-gateway serves ChatContract on 127.0.0.1:8585 (archied and archie-ui dial it; neither embeds a gateway) - * archie-state-store owns archie.db on 127.0.0.1:9090, loopback, + * archie-state-store owns archie.db on 127.0.0.1:9091, loopback, no token (deployments/dev.toml); archied, archie-gateway and archie-ui dial it -- none owns the DB in-process @@ -288,8 +288,8 @@ tasks: on :8484 The gRPC ports come from [services.state].listen and [services.gateway].listen in - deployments/dev.toml, each paired with the target that dials it. Move them there - when the host already owns one: cockpit binds 9090 by default. + deployments/dev.toml, each paired with the target that dials it. Move a pair there + together when a port is already taken on the host. Open http://localhost:5173 -- not :8484. The Vite server is the one with hot reload; :8484 serves the last built dist/ and will look stale. @@ -318,7 +318,7 @@ tasks: # requires (openStateStoreAdapter fails closed on an empty target). # Without it `task dev` leaves the gateway dialling whatever the # developer's installed config names, or unable to start at all, while - # archied, archie-ui and the state store all dial 127.0.0.1:9090. + # archied, archie-ui and the state store all dial 127.0.0.1:9091. cmds: - go run ./cmd/archie-gateway -config-overlay deployments/dev.toml diff --git a/cmd/archie-state-store/main_test.go b/cmd/archie-state-store/main_test.go index c844fbeb9..6546c38c0 100644 --- a/cmd/archie-state-store/main_test.go +++ b/cmd/archie-state-store/main_test.go @@ -322,8 +322,8 @@ func capture(source, body string) store.CapturedEvent { // It also takes its listen address from [services.state].listen rather than // -listen, so the startup path every deployment uses is covered by the process // that exercises the most: before that key existed the address came from a flag -// default with no config key, so a host that already owned the port (cockpit -// owns 9090 by default) could only be retargeted by passing -listen and +// default with no config key, so a host whose port was already taken could +// only be retargeted by passing -listen and // hand-writing an overlay whose target matched -- and the failure read as a // code fault, "address already in use" in the store and a gRPC handshake error // in every client. diff --git a/config.example.toml b/config.example.toml index e5f582a80..e7b9c8474 100644 --- a/config.example.toml +++ b/config.example.toml @@ -348,8 +348,8 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch # listen = "127.0.0.1:9090" # The address archie-state-store BINDS. Read only by that # # process; every client ignores it. Defaults to the target # # above, so a default deployment's client and server cannot -# # drift onto different ports. Move it when the host already -# # owns 9090 (cockpit binds it by default). +# # drift onto different ports. Move it when a port is already +# # taken on the host. # target_token = "..." # bearer token for a NON-loopback target. A loopback target # # (127.0.0.1/::1/localhost) needs no token. A non-loopback # # target without a token fails closed (docs/prds/state-store-contract.md diff --git a/deployments/dev.toml b/deployments/dev.toml index 512af5c3c..058e11fbc 100644 --- a/deployments/dev.toml +++ b/deployments/dev.toml @@ -14,7 +14,7 @@ listen = "127.0.0.1:8484" # `task dev` runs archie-state-store via dev:state-store, which passes no # -listen, so the listen below is the port the store binds. It must agree with # the target: these two lines are the only place that pair is stated. Move them -# when the host already owns 9090 (cockpit binds it by default) -- before the +# when a port is already taken on the host -- before the # listen key existed the collision could only be worked around by hand-writing # a matching target and passing -listen, and it read as a code fault. # (docs/prds/state-store-contract.md ยง12 step 7). diff --git a/internal/app/archied/listen.go b/internal/app/archied/listen.go index d8a5fa3b0..7fad92e00 100644 --- a/internal/app/archied/listen.go +++ b/internal/app/archied/listen.go @@ -12,8 +12,8 @@ import ( // default alone, with no config key. The port a service binds and the port its // clients dial were therefore two separate facts -- the flag default (or a // hand-passed -listen) and [services.].target -- with nothing keeping -// them in step. On a host that already owned the default (cockpit owns 9090) -// retargeting meant hand-writing an overlay and passing a matching flag, and +// them in step. On a host whose default port was already taken, retargeting +// meant hand-writing an overlay and passing a matching flag, and // the failure looked like a code fault: the listener died with "address already // in use" while every client reported a gRPC handshake error against whatever // else held the port. diff --git a/internal/infrastructure/configuration/services_test.go b/internal/infrastructure/configuration/services_test.go index b4896d045..da43e1f9f 100644 --- a/internal/infrastructure/configuration/services_test.go +++ b/internal/infrastructure/configuration/services_test.go @@ -34,8 +34,8 @@ func TestLoadGatewayServiceTarget(t *testing.T) { } // TestLoadServiceListens: both gRPC services this repository runs bind an -// address the configuration names. They used to be flag-only, so a host that -// already owned the default port (cockpit owns 9090) could only be retargeted +// address the configuration names. They used to be flag-only, so a host whose +// default port was already taken could only be retargeted // by passing -listen and hand-writing an overlay whose target matched -- two // files to keep in step, and nothing to keep them there. func TestLoadServiceListens(t *testing.T) {