docker

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 27 Imported by: 0

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

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

func DisplayVersion(ver string) string

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

func EnvImage() (string, error)

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

func Materialize(tld, certDir, image string) (string, error)

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 StackDir

func StackDir() (string, error)

StackDir returns the directory the embedded stack is materialized into.

func VersionSkew added in v0.3.0

func VersionSkew(stackVer string, running bool, cliVer string) string

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

type Composer interface {
	Compose(stackDir string, args ...string) error
}

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

func Routes(ctx context.Context, tld string) ([]Route, error)

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.

func (Route) Display added in v0.9.0

func (r Route) Display() string

Display renders the route's target for `proximo status`: the HTTPS URL for an HTTP route, or a `tcp://host:ports (mode)` summary for a TCP-over-TLS route, suffixed with a balanced marker when more than one backend serves it.

type StackInfo added in v0.11.0

type StackInfo struct {
	Running bool
	Version string
	Image   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

func StackStatus(ctx context.Context) (StackInfo, error)

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".

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

func NewWatcher() (*Watcher, error)

NewWatcher creates a Watcher from the Docker environment and loads the CA (for issuing per-host certificates) from the mounted paths.

func (*Watcher) Run

func (w *Watcher) Run(ctx context.Context) error

Run reconciles once, then reacts to Docker events with a periodic resync.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL