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 ¶
- 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 Materialize(tld, certDir string) (string, error)
- func StackDir() (string, error)
- func StackVersion(ctx context.Context) (ver string, running bool, err error)
- func Up(tld, certDir string) error
- func VersionSkew(stackVer string, running bool, cliVer string) string
- type Composer
- type ConvergeOpts
- type Route
- type Watcher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 build 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. The bring-up always re-pulls (so the pinned Traefik tag picks up security patches); a mobile ref or Force prepends a --no-cache rebuild of the buildable services to defeat a stale `go install @<ref>` layer.
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 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, and returns the stack directory.
func StackVersion ¶ added in v0.3.0
StackVersion reads the proximo.version label from a running stack container (any service carries the role label). running reports whether a stack container was found at all, so callers can tell "no stack" (running false) from "stack predating version stamping" (running true, empty version — a pre-0.4.0 stack carries no version label). Docker errors are returned so callers can tell "stack down" from "Docker broken".
func Up ¶
Up materializes the stack and brings it up (building images as needed), applying any pending convergence to the installed CLI version.
func VersionSkew ¶ added in v0.3.0
VersionSkew returns a human-readable warning when the running stack version differs from the installed CLI version, or "" when they match or the stack is not running. An unlabeled (pre-0.4.0) stack never matches, so it always warns — it must not be mistaken for a stack that is down.
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 rebuilds the in-stack images without the build cache, regardless of
// whether the ref is mobile.
Force bool
}
ConvergeOpts tunes how Converge rebuilds the stack.
type Route ¶
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 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.