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 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 Purge() error
- func StackDir() (string, error)
- func VersionSkew(stackVer string, running bool, cliVer string) string
- type Composer
- type ConvergeOpts
- type Route
- type StackInfo
- type Watcher
Constants ¶
This section is empty.
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 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`.
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 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 Route ¶
type Route struct {
Container string
Host string
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
}
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
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).
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.