docker

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Jun 4, 2026 License: MIT Imports: 26 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 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 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

func Materialize(tld, certDir 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, and returns the stack directory.

func StackDir

func StackDir() (string, error)

StackDir returns the directory the embedded stack is materialized into.

func StackVersion added in v0.3.0

func StackVersion(ctx context.Context) (string, error)

StackVersion reads the proximo.version label from a running stack container (any service carries the role label). It returns "" when no stack container is running or the label is absent; Docker errors are returned so callers can tell "stack down" (empty, nil) from "Docker broken".

func Up

func Up(tld, certDir string) error

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

func VersionSkew(stackVer, 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 (stackVer == "").

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

type Route struct {
	Container string
	Host      string
	URL       string
	Note      string
}

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) ([]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.

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