Documentation
¶
Overview ¶
Package docker materializes and drives the embedded reverse-proxy stack (Traefik + DNS server + network watcher) via `docker compose`, and hosts the network-attach watcher used inside the stack.
Index ¶
- Constants
- func CanonicalImage() string
- func Converge(tld, certDir string, opts ConvergeOpts) error
- func ConvergeObservability(tld, certDir string, opts ConvergeOpts, bootstrap func(stackDir string) error) error
- func DisplayVersion(ver string) string
- func Down() error
- func DownObservability() error
- func EnvImage() (string, error)
- func Materialize(tld, certDir, image string) (string, error)
- func PortKey(port int, proto string) string
- func PublishedPorts(ctx context.Context) (map[string]PortOwner, error)
- func Purge() error
- func StackDir() (string, error)
- type Composer
- type ConvergeOpts
- type PortOwner
- type Route
- type StackInfo
- type Watcher
Constants ¶
const NoteStarting = "starting (waiting for healthy)"
NoteStarting is the note carried by a health-gated container whose healthcheck has not passed yet. It is a moment in a container's life, not a broken environment, which is why a Check must not read it as a failure — exported so the two cannot drift apart as two copies of one string.
const NoteUnhealthy = "unhealthy (route withdrawn until healthy)"
NoteUnhealthy is the note carried by a container whose healthcheck failed, so its route was withdrawn. Unlike NoteStarting it is a fault: the container is up and cannot serve.
Variables ¶
This section is empty.
Functions ¶
func CanonicalImage ¶ added in v0.11.0
func CanonicalImage() string
CanonicalImage is the stack image this CLI pins itself to. An --image override replaces it wholesale; `status` compares against this to tell the developer an override is in effect.
func Converge ¶ added in v0.3.0
func Converge(tld, certDir string, opts ConvergeOpts) error
Converge materializes the embedded stack to disk and brings it up with ref-aware pull freshness. It is the single bring-up path shared by `proximo up`, `install`, and `proximo update`, so "update now" and "update on next start" cannot drift.
func ConvergeObservability ¶ added in v0.3.0
func ConvergeObservability(tld, certDir string, opts ConvergeOpts, bootstrap func(stackDir string) error) error
ConvergeObservability brings the stack up with the opt-in observability profile active. It runs the normal core converge, brings up the log viewer and metrics hub, runs the supplied bootstrap (which must write the agent env file once the hub is reachable), then brings up the metrics agent. Sequencing the agent after the bootstrap guarantees it never starts without its hub credentials (design D4). bootstrap may be nil (e.g. in tests).
func DisplayVersion ¶ added in v0.5.0
DisplayVersion names a stack version for human output. A running stack without a version label predates version stamping (the proximo.version label was introduced in 0.4.0), so an empty version is shown as "pre-0.4.0".
func Down ¶
func Down() error
Down stops and removes the whole stack — core services plus the opt-in observability dashboards — without touching host configuration. A plain `docker compose down` leaves profile-gated services running, so the observability profile must be enabled (and --remove-orphans added) for the dashboards to be torn down together with the core stack.
func DownObservability ¶ added in v0.3.2
func DownObservability() error
DownObservability stops and removes only the opt-in observability services, leaving the core stack running. It is the scoped counterpart to Down behind `proximo down --observability`.
func EnvImage ¶ added in v0.11.0
EnvImage returns the stack image ref recorded in the materialized .env, or "" when nothing has been materialized yet. It is how `up` and `update` see the sticky --image override they are about to keep or clear.
func Materialize ¶
Materialize writes the embedded stack assets to disk, substituting the TLD and the host data-dir path, creates the bind-mounted data subdirectories, copies the TLS material from certDir into the stack, writes the compose environment file pinning the stack image, and returns the stack directory.
func PublishedPorts ¶ added in v0.13.0
PublishedPorts maps each published host port, keyed by PortKey, to the container publishing it. A Check asks who holds a port rather than whether it is free: a healthy machine has :443 bound, by proximo.
Docker is asked rather than inferred from a failed bind, because a bind is not a reliable answer everywhere: on BSD (macOS) SO_REUSEADDR lets a loopback-specific bind succeed while another process holds the wildcard address, which is exactly how Docker publishes :80 and :443.
func Purge ¶ added in v0.11.0
func Purge() error
Purge is Down plus proximo's own stack images — the pinned version in use and every superseded one `update` deliberately left cached. `uninstall` reverses everything proximo put on the host, and those images are one of those things; a plain `down` keeps them, because stopping the stack must not make the next `up` re-download it.
Third-party images (Traefik, the observability dashboards) are left alone: proximo did not author them, and a developer may well be sharing them with another project. That is why this is not `compose down --rmi all`.
Types ¶
type Composer ¶ added in v0.3.0
Composer runs a docker compose subcommand in a materialized stack directory. The production adapter (execComposer) shells out via compose(); tests pass a fake that records the commands so Converge's sequencing is verifiable without Docker. Only execution is bound — composeConvergeCmds stays the pure, tested source of the command sequence.
type ConvergeOpts ¶ added in v0.3.0
type ConvergeOpts struct {
// Force re-pulls the stack image even when its tag is already cached. A
// benign no-op on an immutable vX.Y.Z, and the only way to advance a mobile
// ref that has not changed name.
Force bool
// Image overrides the stack image ref verbatim — a tag, a digest, or a
// locally built image. Empty means CanonicalImage(). It replaces the whole
// stack, never one component, and is written into the materialized .env so
// containers restarting at boot keep it.
Image string
}
ConvergeOpts tunes how Converge brings the stack up.
func (ConvergeOpts) EffectiveImage ¶ added in v0.11.0
func (o ConvergeOpts) EffectiveImage() string
EffectiveImage resolves the ref a converge with these options runs. An explicit --image wins; then a PROXIMO_SRC checkout, which is built rather than pulled; otherwise the version-pinned published ref. Whatever it returns is what the .env records and the services stamp as proximo.image, so the stack can never run one image and declare another — and the CLI must resolve what it reports through here, not re-derive it, for the same reason.
type PortOwner ¶ added in v0.13.0
PortOwner is the container publishing a host port, and whether it is one of proximo's own — which is the difference between a healthy machine and a contested port.
type Route ¶
type Route struct {
Container string
Host string
Qualified string // the qualified host the route also answers on ("" when it has none)
Path string // proximo.path prefix scoping the route ("" = all paths)
URL string
Note string
Middlewares []string // active proximo middlewares (auth/cors/headers), in chain order
TCPPorts []int // backend ports for a TCP-over-TLS (SNI) route; empty means an HTTP route
TLSMode string // TCP TLS mode (terminate/passthrough); set only for TCP routes
Backends int // number of backend containers serving this route; >1 means round-robin balanced
Inspect bool // proximo.inspect asked for, and honoured: the route is served through the hop
InspectNote string // set when proximo.inspect was asked for but could not be honoured
// Collision marks the row as a host another container claimed. It is said
// structurally rather than read back out of Note, so a Check can route a
// collision to its own explanation without pattern-matching prose that is
// written for a human.
Collision bool
}
Route is a routed container and a URL it is reachable at. When Note is set the container opted in but is not effectively served (e.g. an unresolved backend port the watcher skips); URL is then empty and Note explains why.
func Routes ¶
Routes lists the effective routing state `proximo status` reports. It uses the same classifier (classify) the watcher uses to generate routers and certificates, so the two cannot disagree about which hosts are served. A proximo container whose backend port is ambiguous/unresolved (the watcher skips it) is flagged with a Note rather than listed as a working route. The classifyInfo diagnostics are ignored here so status stays quiet — no watcher warnings. tld names the Traefik dashboard self-route host (traefik.<tld>), which the watcher injects outside container classification and is therefore surfaced here the same way: present whenever the stack's Traefik is running.
type StackInfo ¶ added in v0.11.0
type StackInfo struct {
Running bool
Version string
Image string
// Roles are the proximo.role values of the running stack containers, so a
// degraded stack (traefik up, watcher gone) is distinguishable from a
// healthy one — which "is anything running?" alone cannot tell.
Roles []string
}
StackInfo is what the host can read back off a running stack: whether one is running at all, the CLI version that materialized it, and the image ref its Go services were started from.
Running distinguishes "no stack" from "stack predating version stamping" (running, empty Version — a pre-0.4.0 stack carries no version label).
func StackStatus ¶ added in v0.11.0
StackStatus reads the proximo.version and proximo.image labels off the running stack. Docker errors are returned so callers can tell "stack down" from "Docker broken".
func (StackInfo) MissingRoles ¶ added in v0.13.0
MissingRoles returns the core stack services that are not running, in the order they are named above. Empty means the stack is whole.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher keeps Traefik attached to the Docker networks of routed containers and issues a CA-signed certificate per container, written to Traefik's file-provider directory.
func NewWatcher ¶
NewWatcher creates a Watcher from the Docker environment and loads the CA (for issuing per-host certificates) from the mounted paths.