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.
This commit is contained in:
sam committed 2026-09-22 04:09:16 +10:00
1 parent 2b3e2f756f
commit 55ea071092
6 files changed
+13 -13

No files matched your search

+4 -4
View File
@@ -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
+2 -2
View File
@@ -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.
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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).
+2 -2
View File
@@ -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.<name>].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.
@@ -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) {