docker

package
v1.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 50 Imported by: 0

Documentation

Overview

Package docker manages connections to one or more Docker engines and exposes a domain-shaped API (containers, networks, stats, logs) for the rest of the app. Connections are created lazily per host and cached.

Index

Constants

View Source
const LabelComposeProject = labelComposeProject

LabelComposeProject is exported so other packages (e.g. the alert engine, scoping a maintenance window by compose project) can read the same label without duplicating the string.

View Source
const SizeUnknown int64 = -1

SizeUnknown marks a size the daemon did not calculate (a volume from a non-local driver, an image whose shared size was not computed). It is reported as-is rather than as 0, so the UI can say "unknown" instead of presenting a missing value as an empty object.

Variables

AllPolicyRules lists every rule this engine knows how to evaluate, in a stable, deliberate order (roughly: privilege escalation, host-boundary breaks, socket access, then hygiene).

View Source
var ErrUnknownAction = errors.New("docker: unknown container action")

ErrUnknownAction is returned by ContainerAction for unsupported actions.

Functions

func ActiveChanges added in v1.7.0

func ActiveChanges(changes []ServiceChange) int

ActiveChanges counts changes NOT marked Ignored — what should actually read as "still needs attention" after reviewed drift is excluded.

func BindOverrideJSON added in v1.6.0

func BindOverrideJSON(slug string, binds []ProjectBind) ([]byte, error)

BindOverrideJSON builds a compose override that repoints each bind at its seeded volume. It's emitted as JSON (valid YAML, and no new dependency): compose merges service volumes by container target, so listing only the targets we replace leaves every other mount untouched. The volumes are declared external so compose uses the exact names we created rather than prefixing them.

func BuildCheckAvailable added in v1.3.0

func BuildCheckAvailable(ctx context.Context) bool

BuildCheckAvailable reports whether `docker build --check` (BuildKit's Dockerfile linter) is usable. Probed once and cached for the process lifetime.

func BuildRegistries added in v1.7.0

func BuildRegistries(buildContext io.Reader, dockerfile string, buildArgs map[string]string) (hosts, unresolved []string, err error)

BuildRegistries reads the Dockerfile out of a build context (a tar, gzip or not) and returns the registry hosts its images come from: every FROM, and every COPY/ADD --from that names an image rather than a stage. unresolved lists image references whose registry can't be told (a variable with no value), for a warning.

It decides which stored credentials a build sends. The daemon gets them all in one header before it reads a byte of the context, so sending every one handed a remote host the credentials of registries it had nothing to do with.

func ChangeFingerprint added in v1.7.0

func ChangeFingerprint(c ServiceChange) string

ChangeFingerprint identifies the SPECIFIC content of a change, not just its (service, kind) — two "env" changes on the same service with different From/To/Detail get different fingerprints. Used to scope a drift ignore to the exact drift a human reviewed, so it doesn't silently also accept every future, unrelated change of the same kind (see store.ProjectDriftIgnore).

func ComposeAvailable added in v1.2.0

func ComposeAvailable(ctx context.Context) bool

ComposeAvailable reports whether the `docker compose` CLI is usable on the host. The result is probed once and cached for the process lifetime.

func ComposeConfig added in v1.3.0

func ComposeConfig(ctx context.Context, dir, slug string) (string, error)

ComposeConfig validates the project's compose file via `docker compose config --quiet` — the same parser used to deploy, so YAML anchors/aliases, merge keys (`<<`), `${VAR}` interpolation and `extends`/`include` resolve exactly as they will at `up` time. On success it prints nothing; on failure the combined output carries the error (often with a file/line reference).

func ComposeConfigEnv added in v1.7.0

func ComposeConfigEnv(ctx context.Context, dir, slug string, env []string) (string, error)

ComposeConfigEnv is ComposeConfig with an explicit process environment — used when the compose file interpolates a value (e.g. a project secret's placeholder) that must be supplied without ever going through .env or any file on disk.

func ComposeConfigJSON added in v1.3.0

func ComposeConfigJSON(ctx context.Context, dir, slug string) ([]byte, error)

ComposeConfigJSON returns the resolved compose model as JSON (`docker compose config --format json`) — used to build a project overview (services, ports, volumes) and detect issues like duplicate host ports.

func ComposeConfigJSONFiles added in v1.7.0

func ComposeConfigJSONFiles(ctx context.Context, dir, slug string, profiles, env, files []string) ([]byte, error)

ComposeConfigJSONFiles is ComposeConfigJSON with the same profile/env/file selection ComposeUpFiles deploys with — including the COMPOSE_PROFILES neutralization (see composeUp) — so the resolved model includes exactly the services `up` will create. Compose silently omits a service gated behind an inactive profile from a plain `config --format json`, so evaluating policy against ComposeConfigJSON's zero-profile result would miss a violation inside a profile the caller actually selected.

func ComposeDown added in v1.2.0

func ComposeDown(ctx context.Context, dir, slug string, env []string) (string, error)

ComposeDown runs `docker compose -p <slug> down` in dir (removes containers and the project's networks; named volumes are kept, like the CLI default).

func ComposeHostEnv added in v1.5.0

func ComposeHostEnv(h *store.Host) (env []string, cleanup func(), err error)

ComposeHostEnv returns the environment additions that make the `docker compose` CLI target the given host's daemon, plus a cleanup func to call when the command finishes. For the local host it returns (nil, noop). For a TCP host with TLS it materialises the stored certs into a private temp dir and points DOCKER_CERT_PATH at it (the dir is removed by cleanup). For SSH it sets a DOCKER_HOST=ssh:// URL (the CLI tunnels via the system ssh client).

func ComposeProfiles added in v1.2.0

func ComposeProfiles(ctx context.Context, dir, slug string) ([]string, error)

ComposeProfiles lists the profiles defined in the project's compose file (`docker compose config --profiles`), one per line.

func ComposeProfilesEnv added in v1.7.0

func ComposeProfilesEnv(ctx context.Context, dir, slug string, env []string) ([]string, error)

ComposeProfilesEnv is ComposeProfiles with an explicit process environment — see ComposeConfigEnv.

func ComposeProfilesEnvFiles added in v1.7.0

func ComposeProfilesEnvFiles(ctx context.Context, dir, slug string, env, files []string) ([]string, error)

ComposeProfilesEnvFiles is ComposeProfilesEnv with an explicit `-f` file list, for a project whose compose file isn't the default-discovered name (see ComposeConfigJSONFiles, which already takes files for the same reason) — without it, a non-default filename makes the auto-discovery this otherwise relies on either fail outright or resolve profiles from the wrong file.

func ComposeRegistryEnv added in v1.7.0

func ComposeRegistryEnv(auths []store.RegistryAuth) (env []string, cleanup func(), warnings []string, err error)

ComposeRegistryEnv prepares a `docker compose` run to log in with the credentials stored under Registries. Compose reads registry credentials from the Docker CLI config, not from the daemon or the API, so without this a deploy only had whatever `docker login` the server's OS user had done.

It writes a private, temporary config dir and returns the env that points the CLI at it, plus a cleanup that removes it. Call cleanup when the run is over; the file holds passwords. With no stored credentials it changes nothing and returns no env.

The temporary dir is a copy of the user's own config with the stored credentials laid over it, not a blank one:

  • config.json keeps every other key (proxies, aliases, credsStore…), and auths for registries we don't hold credentials for stay as they were.
  • every other entry of the source dir (cli-plugins, contexts, buildx) is linked in, so the compose plugin and the current context are still found.
  • for a registry we hold credentials for, a credential helper the user configured is overridden with an empty helper name, which makes the CLI read the inline auth instead.
  • an inherited DOCKER_AUTH_CONFIG, which the CLI consults before all of the above, is passed on with the stored credentials laid over it too.

The stored credential wins on purpose: it is the one managed in the app.

Problems with the user's own config don't stop the deploy, the same as the Docker CLI only warns about them. They come back as warnings for the output.

func ComposeResolvedConfig added in v1.3.0

func ComposeResolvedConfig(ctx context.Context, dir, slug string) (string, error)

ComposeResolvedConfig returns the fully-resolved compose configuration (`docker compose config` without --quiet): anchors, merge keys, ${VAR} interpolation and extends/include flattened into one canonical YAML — exactly what `up` will deploy. Only stdout (the YAML) is returned; on failure the error carries stderr.

func ComposeResolvedConfigEnv added in v1.7.0

func ComposeResolvedConfigEnv(ctx context.Context, dir, slug string, env []string) (string, error)

ComposeResolvedConfigEnv is ComposeResolvedConfig with an explicit process environment — see ComposeConfigEnv.

func ComposeRestart added in v1.2.0

func ComposeRestart(ctx context.Context, dir, slug string, env []string) (string, error)

ComposeRestart runs `docker compose -p <slug> restart` (restarts the running containers without re-creating them).

func ComposeUp added in v1.2.0

func ComposeUp(ctx context.Context, dir, slug string, profiles []string, env []string, build bool) (string, error)

ComposeUp runs `docker compose -p <slug> [--profile p…] up -d [--build]` in dir and returns the combined stdout+stderr (for display) alongside any error. env adds to the process environment (e.g. DOCKER_HOST to target a remote daemon); nil runs against the local daemon.

func ComposeUpFiles added in v1.6.0

func ComposeUpFiles(ctx context.Context, dir, slug string, profiles, env, files []string, build bool) (string, error)

ComposeUpFiles is ComposeUp with an explicit compose file list, passed as `-f` in order so later files override earlier ones. It's used by a remote deploy, which layers an override repointing bind mounts at seeded volumes. Empty files keeps the CLI's own file discovery.

build adds `--build`. Without it, `up` only builds a service whose image is MISSING — so the second deploy after editing a Dockerfile or a file in the build context silently keeps running the old image, and the CLI reports nothing more alarming than "Container Running". That is the opposite of what the project editor promises, which is why callers deploying edited files pass true. It is a no-op for services that declare no `build:`, so it costs nothing on an image-only project.

func ComposeUpFilesPull added in v1.7.0

func ComposeUpFilesPull(ctx context.Context, dir, slug string, profiles, env, files []string, build bool) (string, error)

ComposeUpFilesPull is ComposeUpFiles with `--pull always` added, so Compose checks the registry for a newer image on every service before recreating.

`up`'s own default pull policy is "missing" — pull only an image that doesn't exist locally at all. That is why reconciling a mutable-tag digest drift (the preview's "digest" change: the tag reads the same, but it now resolves to a different image on the registry) via a plain `up -d` silently does nothing: the stale local image is already present, so it gets reused and the running digest never actually moves, even though the command reports success. Callers that mean to fix exactly that drift need this variant, not ComposeUpFiles.

func ComposeWarnings added in v1.3.0

func ComposeWarnings(out string) []string

ComposeWarnings extracts the human-readable messages from `level=warning` lines in compose CLI output (e.g. `The "X" variable is not set`), which the CLI prints to stderr even for an otherwise-valid file.

func DockerfileCheck added in v1.3.0

func DockerfileCheck(ctx context.Context, content string) (string, error)

DockerfileCheck lints a Dockerfile with `docker build --check` without running any build steps. The content is written to a throwaway build context (the check doesn't read COPY/ADD sources, so the Dockerfile alone is enough). The cleaned check output is returned with BuildKit progress noise stripped; a non-nil error means the check reported problems — lint warnings (exit 255) or a parse error (exit 1) — with the detail in the returned string.

func ExtendServiceComparison added in v1.7.0

func ExtendServiceComparison(prev *DeployPreview, resolved, running []ServiceSpec)

ExtendServiceComparison adds env/port/volume/network/restart/resource/ healthcheck comparisons on top of what BuildDeployPreview already found, for services on both sides that carry full detail (see LiveServiceSpec in deployfields.go) and that BuildDeployPreview/AugmentDigestDrift didn't already flag — any of those already implies a recreate, so a field-level diff on top of one would just be noise.

Every comparison here is deliberately one-directional: it only flags a field the compose file actually DECLARES and disagrees with reality. A field compose is silent on (no env override, no resource limit, no healthcheck) is never compared — there is no stored record of which of a running container's current settings were ever compose-managed (closing that gap is exactly what the planned revision store is for, see NEXT.md), so silence must read as "not judged", never as "removed".

func FirstDuplicateID added in v1.6.1

func FirstDuplicateID(ids []string) string

FirstDuplicateID returns the first id in ids that also appears earlier in ids, or "" if every id is unique. Exported so MCP-layer callers (see internal/mcp/tools_parity.go) can refuse a duplicate-containing batch before spending their own per-container rate-limit budget on it, while BulkContainerAction below applies the same check as its own fail-closed guard for every caller — MCP or the REST bulk endpoint (internal/api/docker_handlers.go).

func ImageRepoKey added in v1.7.0

func ImageRepoKey(ref string) string

ImageRepoKey normalises a reference to "host/repo", dropping any tag or digest — the same host/repo parsing ImageTags and ResolveImageDigest already use, reused here (and by the recovery bundle's compatibility check) so this stays consistent with how the rest of the package decides what "the same image" means.

func MarkIgnoredChanges added in v1.7.0

func MarkIgnoredChanges(changes []ServiceChange, ignored map[[3]string]bool)

MarkIgnoredChanges flags each change matching a (service, kind, fingerprint) a caller has recorded as reviewed drift (store.ProjectDriftIgnore) — it never removes a change from the list, only marks it, so an ignored drift stays visible (and un-ignorable) rather than silently disappearing. The fingerprint requirement means a NEW change of the same (service, kind) but different From/To/Detail is never matched by an old ignore.

func NormalizeProfiles added in v1.6.1

func NormalizeProfiles(profiles []string) []string

NormalizeProfiles trims whitespace, drops empty entries, and deduplicates (keeping first-occurrence order) a caller-supplied profile selection.

This used to happen only inline inside ComposeUpFiles, while callers that persist or audit "the profiles this deploy used" (handleDeployProject) stored the raw, unnormalized input instead. A request like [" prod ", "prod", ""] activated exactly one profile, "prod" — but the stored "last deployed profiles" and the audit log read as three different (and duplicate) values, so the UI's "Deployed with" badge and the audit trail could both misrepresent what was actually running. Exported so a caller can normalize once and pass the SAME slice to the compose command, persistence, and audit, rather than each re-deriving it and risking drift.

func RebaseBindSources added in v1.7.0

func RebaseBindSources(specs []ServiceSpec, fromDir, toDir string)

RebaseBindSources rewrites every bind-mount source under fromDir to the equivalent path under toDir. `docker compose config` resolves a relative bind mount (`./html:...`) to an ABSOLUTE path anchored to whatever directory it was run in — for a revision, that's a throwaway extraction directory, a different one on every call. Without rebasing, comparing a revision's specs against the live project directory (or against another revision's own throwaway directory) would report a "volumes" change for every relative bind mount, on every comparison, whether or not anything about it actually changed.

func RecordHost added in v1.7.0

func RecordHost(ctx context.Context, hostID int64)

RecordHost notes hostID in ctx's recorder, for a caller that knows the host an action is about without connecting to it (an authorisation check on it, say).

func RegistryEnvFromStore added in v1.7.0

func RegistryEnvFromStore(ctx context.Context, st *store.Store) (env []string, cleanup func(), warnings []string, err error)

RegistryEnvFromStore is ComposeRegistryEnv for every credential in st. A stored credential that can't be decrypted is left out and named in warnings.

func SeedVolumeName added in v1.6.0

func SeedVolumeName(slug, rel string) string

SeedVolumeName derives the deterministic name of the volume that carries a project's bind source on a remote host. The relative path is hashed so any path shape yields a valid, collision-resistant Docker volume name.

func TrivyAvailable added in v1.5.0

func TrivyAvailable(ctx context.Context) bool

TrivyAvailable reports whether the `trivy` CLI is usable on the host running Docker Commander. Probed once and cached for the process lifetime.

func ValidImageRef added in v1.5.0

func ValidImageRef(ref string) bool

ValidImageRef reports whether ref is a safe image reference to pass to an external CLI as a positional argument.

Types

type BuildMessage

type BuildMessage struct {
	Stream string `json:"stream,omitempty"`
	Error  string `json:"error,omitempty"`
}

BuildMessage is one line of build output forwarded to the UI. Build streams are mostly free-text (Stream); Error carries a build failure.

type BuildOptions

type BuildOptions struct {
	Tags       []string
	Dockerfile string
	NoCache    bool
	BuildArgs  map[string]string
	// Registries are the registry hosts the Dockerfile pulls from (see
	// BuildRegistries). Only their stored credentials are sent; none at all
	// when it is empty.
	Registries []string
	// Warnings are shown with the build's own warnings, once it is over.
	Warnings []string
}

BuildOptions are the user-facing knobs for an image build.

type BulkActionResult added in v1.6.1

type BulkActionResult struct {
	ID    string `json:"id"`
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
}

BulkActionResult is the outcome of one container's action within a bulk request — one per requested id, in request order.

type CheckResult added in v1.7.0

type CheckResult struct {
	ID      string      `json:"id"`
	Name    string      `json:"name"`
	Status  CheckStatus `json:"status"`
	Message string      `json:"message"`
	Details []string    `json:"details,omitempty"`
}

CheckResult is one row of a diagnostics report.

type CheckStatus added in v1.7.0

type CheckStatus string

CheckStatus is the outcome of one diagnostic check.

const (
	CheckOK      CheckStatus = "ok"
	CheckWarn    CheckStatus = "warn"
	CheckFail    CheckStatus = "fail"
	CheckSkipped CheckStatus = "skipped"
)

type ContainerDetail

type ContainerDetail struct {
	ID            string            `json:"id"`
	Name          string            `json:"name"`
	Image         string            `json:"image"`
	State         string            `json:"state"`
	Status        string            `json:"status"`
	Health        string            `json:"health,omitempty"`
	Created       string            `json:"created"`
	StartedAt     string            `json:"startedAt,omitempty"`
	RestartCount  int               `json:"restartCount"`
	Command       []string          `json:"command"`
	Env           []string          `json:"env"`
	Labels        map[string]string `json:"labels"`
	Mounts        []MountInfo       `json:"mounts"`
	Ports         []PortMapping     `json:"ports"`
	Networks      []NetworkAttach   `json:"networks"`
	RestartPolicy string            `json:"restartPolicy,omitempty"`
}

ContainerDetail is the full inspect view shown on the detail page.

type ContainerSummary

type ContainerSummary struct {
	ID       string            `json:"id"`
	Name     string            `json:"name"`
	Image    string            `json:"image"`
	State    string            `json:"state"`  // running, exited, paused, ...
	Status   string            `json:"status"` // human text, e.g. "Up 3 hours"
	Created  int64             `json:"created"`
	Ports    []PortMapping     `json:"ports"`
	Networks []string          `json:"networks"`
	Labels   map[string]string `json:"labels"`
}

ContainerSummary is a compact view used in lists.

type CreateSpec

type CreateSpec struct {
	Image         string     `json:"image"`
	Name          string     `json:"name"`
	Cmd           []string   `json:"cmd"`
	Env           []string   `json:"env"`   // KEY=VALUE
	Binds         []string   `json:"binds"` // src:dst[:ro]
	Ports         []PortSpec `json:"ports"`
	RestartPolicy string     `json:"restartPolicy"` // "", no, always, unless-stopped, on-failure
	Memory        int64      `json:"memory"`        // bytes, 0 = unset
	NanoCPUs      int64      `json:"nanoCpus"`      // 0 = unset (cpus * 1e9)
	Start         bool       `json:"start"`
}

CreateSpec is the user-facing container create/run request.

type DeployPreview added in v1.6.0

type DeployPreview struct {
	Services  []ServiceSpec   `json:"services"`
	Running   []ServiceSpec   `json:"running"`
	Changes   []ServiceChange `json:"changes"`
	Unchanged int             `json:"unchanged"`
}

DeployPreview is what a deploy would change.

func BuildDeployPreview added in v1.6.0

func BuildDeployPreview(resolved, running []ServiceSpec) DeployPreview

BuildDeployPreview compares the resolved services against what is running.

A service present in both with the same image is counted as unchanged rather than listed: the useful output is what MOVES, and a project with thirty stable services should not bury its one change in a wall of them.

type DiagnosticsReport added in v1.7.0

type DiagnosticsReport struct {
	HostID      int64         `json:"hostId"`
	GeneratedAt time.Time     `json:"generatedAt"`
	Checks      []CheckResult `json:"checks"`
}

DiagnosticsReport is the full battery's result for one host.

type DiffEntry

type DiffEntry struct {
	Kind string `json:"kind"` // modified | added | deleted
	Path string `json:"path"`
}

DiffEntry is one filesystem change in a container relative to its image.

type DiskBuildCache added in v1.7.0

type DiskBuildCache struct {
	Count       int   `json:"count"`
	Size        int64 `json:"size"`
	Reclaimable int64 `json:"reclaimable"` // records not in use
}

DiskBuildCache is the builder cache in aggregate — individual records are not something an operator acts on.

type DiskContainer added in v1.7.0

type DiskContainer struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Project  string `json:"project,omitempty"` // compose project, when there is one
	State    string `json:"state"`
	SizeRw   int64  `json:"sizeRw"`
	SizeRoot int64  `json:"sizeRoot"`
}

DiskContainer is a container's own disk use: the writable layer (SizeRw) on top of its image, and the total including the image (SizeRootFs).

type DiskImage added in v1.7.0

type DiskImage struct {
	ID         string   `json:"id"`
	Tags       []string `json:"tags"`
	Size       int64    `json:"size"`
	Unique     int64    `json:"unique"`     // SizeUnknown when the daemon did not compute shared size
	Containers int64    `json:"containers"` // containers using it; SizeUnknown if not computed
}

DiskImage is one image's footprint. Size is the whole image including every layer; Unique is what deleting it would actually free (Size minus layers other images share). Summing Size across images overcounts, which is why the report carries no image total.

type DiskReclaimable added in v1.7.0

type DiskReclaimable struct {
	Images     int64 `json:"images"`
	Containers int64 `json:"containers"`
	Volumes    int64 `json:"volumes"`
	BuildCache int64 `json:"buildCache"`
	Total      int64 `json:"total"`
}

DiskReclaimable is what could be freed, per category, as Docker itself computes it (the RECLAIMABLE column of `docker system df`): images no container uses (their unique layers), stopped containers' writable layers, volumes no container references, and build cache not in use. For images it is a lower bound — layers shared only among several unused images are counted in none of them, though pruning all of them frees those too.

type DiskReport added in v1.7.0

type DiskReport struct {
	GeneratedAt int64           `json:"generatedAt"` // unix seconds
	Images      []DiskImage     `json:"images"`
	Containers  []DiskContainer `json:"containers"`
	Volumes     []DiskVolume    `json:"volumes"`
	BuildCache  DiskBuildCache  `json:"buildCache"`
	Reclaimable DiskReclaimable `json:"reclaimable"`
}

DiskReport is `docker system df -v` with every object kept, sorted by size (largest first, unknown last) so the UI can answer "what takes the most space" directly.

type DiskUsage

type DiskUsage struct {
	LayersSize int64         `json:"layersSize"`
	Images     UsageCategory `json:"images"`
	Containers UsageCategory `json:"containers"`
	Volumes    UsageCategory `json:"volumes"`
	BuildCache UsageCategory `json:"buildCache"`
}

DiskUsage summarises what Docker is storing (docker system df).

type DiskVolume added in v1.7.0

type DiskVolume struct {
	Name     string `json:"name"`
	Driver   string `json:"driver"`
	Project  string `json:"project,omitempty"`
	Size     int64  `json:"size"`
	RefCount int64  `json:"refCount"` // SizeUnknown if not available
}

DiskVolume is a volume's size (SizeUnknown for non-local drivers) and how many containers reference it.

type Event

type Event struct {
	Action        string // "die", "start", "stop", "kill", "oom", "health_status: unhealthy", ...
	ContainerID   string
	ContainerName string
	Image         string
	ExitCode      string
	// Project is the container's compose project (stack) name, read from the
	// event's own actor attributes — Docker includes the full label set on
	// every container event, so this needs no extra call. Populated live,
	// unlike a stats-snapshot lookup, so a container created moments ago (and
	// not yet in any poll) still resolves correctly — see the alert engine's
	// use of this for maintenance-window project scoping.
	Project string
}

Event is a simplified container lifecycle event for the monitor/alert engine.

type EventMsg

type EventMsg struct {
	Time   int64             `json:"time"`
	Type   string            `json:"type"`   // container | image | network | volume | …
	Action string            `json:"action"` // start | die | pull | create | …
	ID     string            `json:"id"`
	Name   string            `json:"name"`
	Attr   map[string]string `json:"attr,omitempty"`
}

EventMsg is one Docker daemon event, flattened for the UI.

type ExecSession

type ExecSession struct {
	// contains filtered or unexported fields
}

ExecSession is a live interactive exec attached to a container. It is a bidirectional byte stream (Read = container output, Write = stdin) plus a Resize control. Works for any host kind, since it goes through the Docker API.

func (*ExecSession) Close

func (s *ExecSession) Close()

Close tears down the hijacked connection.

func (*ExecSession) Conn

func (s *ExecSession) Conn() net.Conn

Conn exposes the underlying connection (for setting deadlines if needed).

func (*ExecSession) Read

func (s *ExecSession) Read(p []byte) (int, error)

Read returns container output (stdout+stderr merged, since TTY).

func (*ExecSession) Resize

func (s *ExecSession) Resize(ctx context.Context, cols, rows uint) error

Resize updates the remote TTY dimensions.

func (*ExecSession) Write

func (s *ExecSession) Write(p []byte) (int, error)

Write sends bytes to the exec's stdin.

type FileEntry

type FileEntry struct {
	Name   string `json:"name"`
	IsDir  bool   `json:"isDir"`
	IsLink bool   `json:"isLink"`
	Size   int64  `json:"size"`
	Mode   string `json:"mode"`
	Target string `json:"target,omitempty"` // symlink target
}

FileEntry is one item in a container directory listing.

type HealthcheckSpec added in v1.7.0

type HealthcheckSpec struct {
	Test     []string      `json:"test,omitempty"`
	Interval time.Duration `json:"interval,omitempty"`
	Timeout  time.Duration `json:"timeout,omitempty"`
	Retries  int           `json:"retries,omitempty"`
}

HealthcheckSpec is a service's healthcheck, normalised to comparable units (compose gives durations as strings like "30s"; a live container gives nanoseconds — both land here as time.Duration).

type HistoryEntry

type HistoryEntry struct {
	ID        string   `json:"id"`
	Created   int64    `json:"created"`
	CreatedBy string   `json:"createdBy"`
	Size      int64    `json:"size"`
	Comment   string   `json:"comment"`
	Tags      []string `json:"tags"`
}

HistoryEntry is one layer in an image's build history.

type HostKeyMismatchError

type HostKeyMismatchError struct {
	Fingerprint string // SHA256:… of the key actually presented now
}

HostKeyMismatchError is returned when the presented key differs from the one we already trust. This is a hard stop: it can mean a reinstalled host — or a man-in-the-middle. We never auto-accept; the operator must re-trust manually.

func (*HostKeyMismatchError) Error

func (e *HostKeyMismatchError) Error() string

type HostKeyUnknownError

type HostKeyUnknownError struct {
	Fingerprint string // SHA256:… of the presented key
	KeyType     string // e.g. "ssh-ed25519"
}

HostKeyUnknownError is returned on first contact with an SSH host whose key is neither pinned in the DB nor present in ~/.ssh/known_hosts. The caller can surface the fingerprint to the operator and, on explicit approval, pin it.

func (*HostKeyUnknownError) Error

func (e *HostKeyUnknownError) Error() string

type HostPortProbe added in v1.1.0

type HostPortProbe struct {
	ContainerID   string `json:"containerId"`
	ContainerName string `json:"containerName"`
	PortProbe
}

HostPortProbe is one published port on the host, tagged with the container that owns it — the rows behind the host-wide "open ports" view.

type HostRecorder added in v1.7.0

type HostRecorder struct {
	// contains filtered or unexported fields
}

HostRecorder notes which Docker host a request actually talked to, so the audit entry for it can say where the action happened.

It is filled in by Manager.Client, the one place every daemon connection is made, after "no host given" has been resolved to the concrete default host. Recording it there, rather than at each of the many audit calls, means a new handler is covered without having to remember to pass the host along.

func HostRecorderFrom added in v1.7.0

func HostRecorderFrom(ctx context.Context) *HostRecorder

HostRecorderFrom returns the recorder in ctx, or nil.

func WithHostRecorder added in v1.7.0

func WithHostRecorder(ctx context.Context) (context.Context, *HostRecorder)

WithHostRecorder returns ctx carrying a fresh recorder.

func (*HostRecorder) Host added in v1.7.0

func (r *HostRecorder) Host() (int64, bool)

Host returns the recorded host, and whether one was recorded.

type ImagePruneResult

type ImagePruneResult struct {
	Deleted        []string `json:"deleted"`
	SpaceReclaimed uint64   `json:"spaceReclaimed"`
}

ImagePruneResult reports what a dangling-image prune removed.

type ImageSearchResult added in v1.4.0

type ImageSearchResult struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Stars       int    `json:"stars"`
	Official    bool   `json:"official"`
}

ImageSearchResult is one Docker Hub search hit.

type ImageSummary

type ImageSummary struct {
	ID          string   `json:"id"`
	RepoTags    []string `json:"repoTags"`
	RepoDigests []string `json:"repoDigests"`
	Size        int64    `json:"size"`
	Created     int64    `json:"created"` // unix seconds
	Dangling    bool     `json:"dangling"`
	InUse       bool     `json:"inUse"` // referenced by an existing container
}

ImageSummary is a compact view of a local image for the Images page.

type LogLine

type LogLine struct {
	Stream    string `json:"stream"` // "stdout" | "stderr"
	Message   string `json:"message"`
	Timestamp string `json:"timestamp,omitempty"`
}

LogLine is one line emitted from a container log stream.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns Docker client connections keyed by host ID.

func NewManager

func NewManager(s *store.Store) *Manager

NewManager returns a manager that resolves hosts from the store.

func (*Manager) AugmentDigestDrift added in v1.7.0

func (m *Manager) AugmentDigestDrift(ctx context.Context, hostID int64, prev *DeployPreview, containers []StackContainer)

AugmentDigestDrift checks, for each service BuildDeployPreview judged unchanged, whether its image tag now resolves to a different manifest digest on its registry than what is actually running — the "mutable tag" case a name/image string comparison can't see (the tag reads the same, but `docker compose up` would still recreate the container). Mutates prev in place, appending a "digest" change per service found to have drifted and correcting Unchanged to match.

Best-effort by design: any lookup failure (registry unreachable, host not configured, image never pulled from a registry) just skips that service — this only ever informs a preview, never blocks one.

func (*Manager) AugmentDigestDriftChecked added in v1.7.0

func (m *Manager) AugmentDigestDriftChecked(ctx context.Context, hostID int64, prev *DeployPreview, containers []StackContainer) map[string]bool

AugmentDigestDriftChecked does the same work as AugmentDigestDrift, and additionally returns which services it positively confirmed to be unchanged (both the registry and the running-container digest resolved, and they matched). A service can be ABSENT from that set for two very different reasons — no image, not currently running, already flagged by BuildDeployPreview, or a registry/inspect lookup failure — and callers that need to tell "confirmed unchanged" apart from "unknown" (e.g. to decide whether it's safe to clear their own dedup state) must consult this returned set rather than inferring it from the absence of a "digest" change in prev.Changes.

func (*Manager) BuildImage

func (m *Manager) BuildImage(ctx context.Context, hostID int64, buildContext io.Reader, opts BuildOptions, onMsg func(BuildMessage)) error

BuildImage builds an image from a tar (optionally gzip'd) build context, streaming the daemon's output line by line. The context reader is supplied by the caller (typically the uploaded request body).

func (*Manager) BulkContainerAction added in v1.6.1

func (m *Manager) BulkContainerAction(ctx context.Context, hostID int64, ids []string, action string) ([]BulkActionResult, error)

BulkContainerAction runs action (restart|stop — callers must validate the action before calling this; ContainerAction itself rejects anything else) against each of ids, bounded to bulkActionConcurrency concurrent daemon calls. One container failing does not stop the others: every id gets a result, success or error, so the caller can report a per-container summary instead of a single aggregate ok/fail.

Rejects a batch containing the same id twice, naming the duplicate, before running anything: one goroutine is started per INDEX, not per unique id, so [id, id] would otherwise fire two concurrent actions at the same container — a race, plus a doubled audit entry, for no legitimate request shape. Matches this package's fail-closed style elsewhere (the stack-membership check below): refuse the whole call, name the offender, execute nothing.

func (*Manager) BulkStackContainerAction added in v1.6.1

func (m *Manager) BulkStackContainerAction(ctx context.Context, hostID int64, project string, ids []string, action string) ([]BulkActionResult, error)

BulkStackContainerAction restarts or stops a caller-chosen subset of one Compose stack's own containers. It is the middle ground between ContainerAction (one container) and StackAction (every container in the stack, unbounded): every id in ids must belong to project — verified here against the stack's `com.docker.compose.project` label, not trusted from the caller — or the WHOLE call is refused, naming the first id that doesn't belong. A partial match never partially executes; that would let a caller reach one container it never actually named the stack for.

Scoping to a project the caller already named keeps this no wider in spirit than restart_stack/stop_stack: those act on every container of a stack the caller identified by name, this acts on a bounded slice of the same set. Restricting action to restart/stop (never start, pause, kill, ...) matches the same restriction the MCP tools built on this apply.

On success it delegates to BulkContainerAction for the actual bounded-parallel execution — this function only adds the membership check.

func (*Manager) Client

func (m *Manager) Client(ctx context.Context, hostID int64) (*client.Client, error)

Client returns a connected Docker client for the given host ID, creating and caching it on first use. A hostID <= 0 means "the default local host", which lets clients (REST and WebSocket) omit the host when targeting localhost.

func (*Manager) Close

func (m *Manager) Close()

Close disconnects all cached clients.

func (*Manager) CloseVolumeBrowser added in v1.3.0

func (m *Manager) CloseVolumeBrowser(ctx context.Context, hostID int64, volume string)

CloseVolumeBrowser removes the helper container(s) for a volume (called when the user closes the browser).

func (*Manager) CommitContainer

func (m *Manager) CommitContainer(ctx context.Context, hostID int64, id, ref, comment string) (string, error)

CommitContainer snapshots a container into a new image (reference repo:tag).

func (*Manager) ConnectNetwork added in v1.3.0

func (m *Manager) ConnectNetwork(ctx context.Context, hostID int64, netID, containerID string) error

ConnectNetwork attaches a container to a network.

func (*Manager) ContainerAction

func (m *Manager) ContainerAction(ctx context.Context, hostID int64, id, action string) error

ContainerAction performs a lifecycle action: start, stop, restart, pause, unpause, kill. Unknown actions return an error.

func (*Manager) ContainerDiff

func (m *Manager) ContainerDiff(ctx context.Context, hostID int64, id string) ([]DiffEntry, error)

ContainerDiff lists filesystem changes since the container started.

func (*Manager) ContainerTop

func (m *Manager) ContainerTop(ctx context.Context, hostID int64, id string) (*TopResult, error)

ContainerTop returns the processes running inside a container.

func (*Manager) CopyFrom

func (m *Manager) CopyFrom(ctx context.Context, hostID int64, id, path string) (io.ReadCloser, container.PathStat, error)

CopyFrom streams a path out of a container as a TAR archive along with its stat (so the caller can tell a file from a directory). Caller closes the reader.

func (*Manager) CopyTo

func (m *Manager) CopyTo(ctx context.Context, hostID int64, id, destDir string, content io.Reader) error

CopyTo writes a TAR archive into the container at destDir.

func (*Manager) CreateContainer

func (m *Manager) CreateContainer(ctx context.Context, hostID int64, spec CreateSpec) (string, error)

CreateContainer creates (and optionally starts) a container from a spec.

func (*Manager) CreateNetwork added in v1.3.0

func (m *Manager) CreateNetwork(ctx context.Context, hostID int64, req NetworkCreateRequest) (string, error)

CreateNetwork creates a user-defined network and returns its ID.

func (*Manager) CreateVolume

func (m *Manager) CreateVolume(ctx context.Context, hostID int64, name, driver string, labels map[string]string) (*VolumeSummary, error)

CreateVolume creates a named volume with an optional driver.

func (*Manager) DeletePath

func (m *Manager) DeletePath(ctx context.Context, hostID int64, id, path string) error

DeletePath removes a path inside the container (rm -rf).

func (*Manager) Disconnect

func (m *Manager) Disconnect(hostID int64)

Disconnect drops the cached client for a host (e.g. after it is deleted or reconfigured), so the next use reconnects with fresh settings.

func (*Manager) DisconnectNetwork added in v1.3.0

func (m *Manager) DisconnectNetwork(ctx context.Context, hostID int64, netID, containerID string, force bool) error

DisconnectNetwork detaches a container from a network (force allows removing a running container's endpoint).

func (*Manager) DiskReport added in v1.7.0

func (m *Manager) DiskReport(ctx context.Context, hostID int64, force bool) (*DiskReport, error)

DiskReport returns the per-object disk report for a host. `system df -v` is expensive on a busy daemon (it walks every volume and container), so results are cached per host: a normal call reuses a report up to diskReportTTL old, and force (a user pressing Refresh) recomputes unless the cached one is under diskReportMinAge old — a floor that keeps a stuck client or a double-click from hammering the daemon. Concurrent calls for one host wait for the same computation instead of each running their own.

func (*Manager) DiskUsage

func (m *Manager) DiskUsage(ctx context.Context, hostID int64) (*DiskUsage, error)

DiskUsage reports how much disk Docker objects occupy (docker system df).

func (*Manager) ExecAttach

func (m *Manager) ExecAttach(ctx context.Context, hostID int64, containerID string, cmd []string, cols, rows uint) (*ExecSession, error)

ExecAttach starts a TTY exec in the container and attaches to it. Pass cmd to override the shell. cols/rows seed the initial terminal size.

func (*Manager) ExportContainer

func (m *Manager) ExportContainer(ctx context.Context, hostID int64, id string) (io.ReadCloser, error)

ExportContainer streams a container's filesystem as a tar archive.

func (*Manager) ImageHistory

func (m *Manager) ImageHistory(ctx context.Context, hostID int64, ref string) ([]HistoryEntry, error)

ImageHistory returns the layer history of an image.

func (*Manager) ImageTags added in v1.4.0

func (m *Manager) ImageTags(ctx context.Context, ref string) ([]string, error)

ImageTags lists tags for an image reference. Docker Hub repos use Hub's public API; for any other host, if the admin has configured it as a registry, tags come from that registry's v2 API (with credentials). Unconfigured hosts return no tags — so a ref can never make us contact an arbitrary host — and callers fall back to whatever the daemon already has pulled locally.

func (*Manager) ImportImage

func (m *Manager) ImportImage(ctx context.Context, hostID int64, tarball io.Reader, ref string) (string, error)

ImportImage creates an image from a filesystem tarball (docker import), tagging it as ref. It returns the daemon's output summary.

func (*Manager) InspectContainer

func (m *Manager) InspectContainer(ctx context.Context, hostID int64, id string) (*ContainerDetail, error)

InspectContainer returns the detailed view of a single container.

func (*Manager) InspectRaw

func (m *Manager) InspectRaw(ctx context.Context, hostID int64, kind, id string) (json.RawMessage, error)

InspectRaw returns the daemon's raw JSON for an object, preserving every field (more faithful than re-marshalling the SDK struct). kind is one of container, image, network, volume.

func (*Manager) ListContainers

func (m *Manager) ListContainers(ctx context.Context, hostID int64) ([]ContainerSummary, error)

ListContainers returns a compact summary of all containers on the host.

func (*Manager) ListImages

func (m *Manager) ListImages(ctx context.Context, hostID int64) ([]ImageSummary, error)

ListImages returns local images, flagging which are untagged ("dangling") and which are referenced by an existing container (so the UI can warn before removing one that is in use).

func (*Manager) ListNetworks

func (m *Manager) ListNetworks(ctx context.Context, hostID int64) ([]NetworkSummary, error)

ListNetworks returns networks plus the set of containers attached to each, which the frontend uses to draw the connectivity topology.

func (*Manager) ListPath

func (m *Manager) ListPath(ctx context.Context, hostID int64, id, path string) ([]FileEntry, error)

ListPath lists one directory level inside a container by running `ls`. It is shell-independent (direct argv) but needs an `ls` binary in the image.

func (*Manager) ListSeedVolumes added in v1.6.0

func (m *Manager) ListSeedVolumes(ctx context.Context, hostID int64, slug string) ([]string, error)

ListSeedVolumes returns the names of the volumes seeded for a project on a host, found by the label the seeding stamps on them.

func (*Manager) ListStacks added in v1.2.0

func (m *Manager) ListStacks(ctx context.Context, hostID int64) ([]Stack, error)

ListStacks groups the host's containers into Compose stacks by their `com.docker.compose.project` label. Containers without the label are ignored.

func (*Manager) ListVolumes

func (m *Manager) ListVolumes(ctx context.Context, hostID int64) ([]VolumeSummary, error)

ListVolumes returns all volumes, cross-referencing containers' mounts so the UI can show (and warn about) volumes that are still in use.

func (*Manager) LiveServiceSpec added in v1.7.0

func (m *Manager) LiveServiceSpec(ctx context.Context, hostID int64, containerID string) (ServiceSpec, error)

LiveServiceSpec inspects a running container and reports its actual config in the same shape as the resolved (compose) side, so the two can be compared field for field. containerID must belong to hostID.

func (*Manager) LiveServices added in v1.7.0

func (m *Manager) LiveServices(ctx context.Context, hostID int64, containers []StackContainer) []ServiceSpec

LiveServices reduces a stack's containers to one full ServiceSpec per compose service (first container per service, same reduction as RunningServices) via a LiveServiceSpec inspect each — the expensive counterpart used when a caller wants the full plan/diff, not just the image comparison. Best-effort: a service whose inspect fails is left out entirely rather than failing the whole preview over one container.

func (*Manager) LoadImage

func (m *Manager) LoadImage(ctx context.Context, hostID int64, tar io.Reader) (string, error)

LoadImage loads images from a tar archive (docker save format) and returns the daemon's human-readable summary (e.g. "Loaded image: repo:tag").

func (*Manager) MakeDir added in v1.3.0

func (m *Manager) MakeDir(ctx context.Context, hostID int64, id, path string) error

MakeDir creates a directory inside the container (mkdir -p).

func (*Manager) NetworkEndpointTraffic added in v1.6.0

func (m *Manager) NetworkEndpointTraffic(ctx context.Context, hostID int64, networkName string, lookup statsFor) (*NetworkStats, error)

NetworkEndpointTraffic builds the endpoint view for one network.

func (*Manager) Ping added in v1.4.0

func (m *Manager) Ping(ctx context.Context, hostID int64) error

SystemInfo returns a summary of the Docker host. Ping reports whether a host's Docker daemon is reachable: nil if the daemon answers, or the dial/ping error otherwise. It is cheaper than SystemInfo (no full Info call) and is used by the monitor's health loop.

func (*Manager) ProbeContainerPorts added in v1.1.0

func (m *Manager) ProbeContainerPorts(ctx context.Context, hostID int64, containerID string) ([]PortProbe, error)

ProbeContainerPorts actively fingerprints every published TCP port of a container: it connects (locally, or tunnelled through SSH for ssh hosts) and classifies the listener by banner / HTTP / TLS / Redis handshake. UDP and unpublished ports get a passive guess only.

func (*Manager) ProbeHostKey

func (m *Manager) ProbeHostKey(ctx context.Context, hostID int64) (keyLine, fingerprint string, err error)

ProbeHostKey connects to an SSH host and returns its presented public key (authorized_keys line) and SHA256 fingerprint, trusting whatever is offered. It is used only by the explicit trust flow, so the operator can pin a key after reviewing its fingerprint.

func (*Manager) ProbeHostPorts added in v1.1.0

func (m *Manager) ProbeHostPorts(ctx context.Context, hostID int64) ([]HostPortProbe, error)

ProbeHostPorts scans every published port of every running container on the host — the host-wide "open ports" map. Probes run in one bounded pool so a busy host doesn't open a flood of connections at once.

func (*Manager) ProjectVolumeNames added in v1.7.0

func (m *Manager) ProjectVolumeNames(ctx context.Context, hostID int64, project string) ([]string, error)

ProjectVolumeNames returns the named volumes Docker Compose actually created for a project, found via the authoritative com.docker.compose.project label — not guessed from the compose file's declared (unprefixed) volume names, which compose runtime-prefixes.

func (*Manager) PruneImages

func (m *Manager) PruneImages(ctx context.Context, hostID int64) (*ImagePruneResult, error)

PruneImages removes dangling images and reports what was reclaimed.

func (*Manager) PruneNetworks added in v1.3.0

func (m *Manager) PruneNetworks(ctx context.Context, hostID int64) ([]string, error)

PruneNetworks removes all unused user-defined networks and returns the names the daemon deleted.

func (*Manager) PruneVolumes

func (m *Manager) PruneVolumes(ctx context.Context, hostID int64) (*VolumePruneResult, error)

PruneVolumes removes all unused (anonymous and named) volumes.

func (*Manager) PullImage

func (m *Manager) PullImage(ctx context.Context, hostID int64, ref string, onProgress func(PullProgress)) error

PullImage pulls a reference and reports progress via onProgress until the stream completes. The Docker daemon emits newline-delimited JSON messages; we decode them and translate to PullProgress. A message carrying an error aborts the pull with that error.

func (*Manager) PushImage

func (m *Manager) PushImage(ctx context.Context, hostID int64, ref string, onProgress func(PullProgress)) error

PushImage pushes a reference to its registry, streaming progress like a pull. Pushing requires credentials for the target registry; without them we fail early with a clear message rather than letting the daemon return a raw 401.

func (*Manager) ReapAllVolumeHelpers added in v1.3.0

func (m *Manager) ReapAllVolumeHelpers(ctx context.Context)

ReapAllVolumeHelpers clears every volume-browser helper on the default host (called at startup to remove orphans from a previous run).

func (*Manager) RecentEvents added in v1.4.0

func (m *Manager) RecentEvents(ctx context.Context, hostID int64, since time.Duration, limit int) ([]EventMsg, error)

RecentEvents returns daemon events from the last `since` window, newest-last, capped at `limit`. Unlike StreamEvents it is bounded: setting Until makes the daemon replay the historical window and then close the stream (io.EOF), so this returns rather than tailing live. Used by the read-only MCP events tool.

func (*Manager) RegistryLogin

func (m *Manager) RegistryLogin(ctx context.Context, hostID int64, a store.RegistryAuth) error

RegistryLogin verifies a set of credentials against a registry via the daemon.

func (*Manager) RemoveImage

func (m *Manager) RemoveImage(ctx context.Context, hostID int64, ref string, force bool) ([]string, error)

RemoveImage deletes an image by ID or reference. force allows removing an image that is tagged multiple times or referenced by stopped containers. It returns the list of untagged/deleted references for the UI.

func (*Manager) RemoveNetwork

func (m *Manager) RemoveNetwork(ctx context.Context, hostID int64, id string) error

RemoveNetwork deletes a user-defined network. The daemon refuses to remove predefined networks (bridge/host/none) or ones with attached endpoints, and that error is surfaced to the caller.

func (*Manager) RemoveSeedVolumes added in v1.6.0

func (m *Manager) RemoveSeedVolumes(ctx context.Context, hostID int64, slug string) (removed []string, err error)

RemoveSeedVolumes deletes a project's seeded volumes on a host, returning the names actually removed. Only volumes carrying this project's seed label are touched — never a host-global prune. Errors for individual volumes are collected rather than aborting, so one still-in-use volume doesn't strand the rest.

func (*Manager) RemoveVolume

func (m *Manager) RemoveVolume(ctx context.Context, hostID int64, name string, force bool) error

RemoveVolume deletes a volume. force removes it even if the metadata claims a reference; the daemon still refuses volumes actively mounted by a container.

func (*Manager) RenameContainer

func (m *Manager) RenameContainer(ctx context.Context, hostID int64, id, newName string) error

RenameContainer changes a container's name.

func (*Manager) ResolveHostID added in v1.2.0

func (m *Manager) ResolveHostID(ctx context.Context, hostID int64) (int64, error)

ResolveHostID maps hostID <= 0 to the default local host's ID.

func (*Manager) ResolveImageDigest added in v1.7.0

func (m *Manager) ResolveImageDigest(ctx context.Context, ref string) (string, error)

ResolveImageDigest looks up the manifest digest an image reference currently resolves to on its registry. Returns "" (not an error) when the registry isn't reachable, isn't configured, or doesn't answer with a digest — this only ever informs a preview, so an unknown answer must never block one.

func (*Manager) ResourceOverview added in v1.1.0

func (m *Manager) ResourceOverview(ctx context.Context, hostID int64) (ResourceOverview, error)

ResourceOverview samples every running container and reports each one's share of the host's total CPU and memory. Per-container stats are gathered concurrently (bounded); a container that fails to sample is simply omitted.

func (*Manager) RunBackupJob added in v1.7.0

func (m *Manager) RunBackupJob(ctx context.Context, hostID int64, image, command string, env map[string]string, mounts map[string]string, timeout time.Duration) (output string, exitCode int, err error)

RunBackupJob runs command (as `sh -c <command>`) inside a throwaway helper container with mounts (volume name -> mount path) bind-mounted, capturing combined stdout/stderr output and the exit code. The container is created, started, waited on and removed unconditionally — nothing about it persists.

Running the user's command inside a container, not via host SSH exec, is the deliberate design boundary: an admin configuring a backup job already has full Docker API control (can already run anything via the existing container-create flows), so this adds no new class of capability — just a convenient, scheduled packaging of one that exists, contained the way a raw host shell command would not be.

func (*Manager) RunDiagnostics added in v1.7.0

func (m *Manager) RunDiagnostics(ctx context.Context, hostID int64) (*DiagnosticsReport, error)

RunDiagnostics runs the full check battery against one host. It fetches each shared input once and hands already-fetched data to the (pure) individual checks, in a fixed order that the UI renders as-is.

func (*Manager) RunningImageDigest added in v1.7.0

func (m *Manager) RunningImageDigest(ctx context.Context, hostID int64, containerID, ref string) (string, error)

RunningImageDigest resolves the digest a container's local image actually carries for ref's repository — what is really deployed right now, as opposed to what the tag currently resolves to on the registry (ResolveImageDigest). Returns "" when the image was never pulled from a registry (built locally, no RepoDigests): that means drift can't be judged for this service, not that something is wrong.

func (*Manager) SampleStats

func (m *Manager) SampleStats(ctx context.Context, hostID int64, id string) (StatsSample, error)

SampleStats fetches a single (non-streaming) stats frame and computes one sample. Used by the monitor for periodic polling and the Prometheus exporter.

func (*Manager) SaveImage

func (m *Manager) SaveImage(ctx context.Context, hostID int64, refs []string) (io.ReadCloser, error)

SaveImage streams one or more images as a tar archive (docker save format). The caller is responsible for closing the returned reader.

func (*Manager) SearchImages added in v1.4.0

func (m *Manager) SearchImages(ctx context.Context, hostID int64, term string, limit int) ([]ImageSearchResult, error)

SearchImages proxies a Docker Hub repository search through the host daemon's /images/search. term is the partial name the user is typing.

func (*Manager) SeedProjectBinds added in v1.6.0

func (m *Manager) SeedProjectBinds(ctx context.Context, hostID int64, projectDir, slug string, binds []ProjectBind) error

SeedProjectBinds creates and fills the volume behind each internal bind on the target host: the local files are streamed in as a TAR through a helper container. Existing content is overwritten so a redeploy ships current files.

func (*Manager) SnapshotSeedVolumes added in v1.7.0

func (m *Manager) SnapshotSeedVolumes(ctx context.Context, hostID int64, slug string, binds []ProjectBind) (*SeedSnapshot, error)

SnapshotSeedVolumes copies out the current content of every seed volume the binds use. A volume that doesn't exist yet is noted, so Restore removes it rather than leaving one the restore created.

func (*Manager) StackAction added in v1.2.0

func (m *Manager) StackAction(ctx context.Context, hostID int64, project, action string) error

StackAction applies a lifecycle action to every container in a stack: start / stop / restart, or remove (force-removes the containers and then the project's Compose networks, leaving named volumes intact — like `docker compose down`).

func (*Manager) StackActionOnIDs added in v1.6.1

func (m *Manager) StackActionOnIDs(ctx context.Context, hostID int64, ids []string, action string) error

StackActionOnIDs applies a lifecycle action (start/stop/restart) to exactly the given container ids, without re-resolving stack membership.

For a caller that already resolved a stack's container ids via StackContainerIDs and sized something against that exact set — an MCP rate-limit charge, for one — calling StackAction instead would re-query membership internally via a SECOND StackContainerIDs call, and could act on a DIFFERENT, larger set than the one just charged for if a concurrent deploy added containers to the project in between: the limiter would have spent units for N containers while this actually touched N+k. Acting on the exact ids already resolved (not asking Docker again "what's in this project right now") is what keeps the two in agreement.

ids is trusted as-is — this is for internal callers that already resolved it from StackContainerIDs, not for an externally-supplied id list. See BulkStackContainerAction for the membership-VERIFYING equivalent used when ids comes from an untrusted caller instead.

func (*Manager) StackCompose added in v1.6.0

func (m *Manager) StackCompose(ctx context.Context, hostID int64, project string) (StackComposeView, error)

StackCompose reads a stack's compose file and reports whether the app can write it back, with the reason when it can't — the UI needs the reason to explain why an editor isn't on offer rather than silently omitting it.

Read and editability come from one call because resolving a stack costs a container list plus a file read, and over SSH that is a network round trip each. Answering both from a single resolution keeps opening the viewer to one.

func (*Manager) StackComposeFile added in v1.2.0

func (m *Manager) StackComposeFile(ctx context.Context, hostID int64, project string) (path, content string, err error)

StackComposeFile best-effort reads and returns the stack's compose file. The file lives on the host (its path comes from the compose labels), so we read it directly for the local daemon or over SSH for ssh hosts. TCP hosts give us no filesystem access. Returns the resolved path and contents.

func (*Manager) StackContainerIDs added in v1.6.1

func (m *Manager) StackContainerIDs(ctx context.Context, hostID int64, project string) ([]string, error)

StackContainerIDs returns the ids of every container in hostID's project (matched on the compose-project label), in no particular order. Exported so a caller can size something — an MCP rate-limit charge, a confirmation prompt — against a stack's actual container count before committing to an action that touches all of them, the way StackAction itself is about to.

func (*Manager) StackRedeploy added in v1.6.0

func (m *Manager) StackRedeploy(ctx context.Context, hostID int64, project string) (string, error)

StackRedeploy runs `docker compose up -d --build` for a CLI-discovered stack, in the working directory it was originally deployed from, so relative paths in the file resolve exactly as they did the first time. It returns the CLI output.

`--build` for the same reason project deploys pass it: `up` builds a service only when its image is MISSING, so a stack declaring `build:` would keep running the image from its first deploy no matter what changed in the Dockerfile or its context, while the CLI reported "Container Running". It is a no-op for services that only pull an image.

`--remove-orphans` is deliberately NOT passed: a redeploy after an edit should not silently delete containers, and compose warns about orphans in the output the caller displays, so removing one stays an explicit choice.

func (*Manager) StackWriteComposeFile added in v1.6.0

func (m *Manager) StackWriteComposeFile(ctx context.Context, hostID int64, project, content string) (string, error)

StackWriteComposeFile replaces a CLI-discovered stack's compose file with content, after checking that the new file is one compose will accept. It returns the path written.

The previous contents are kept alongside as <name><dcBackupSuffix>. Nothing is written until the replacement validates, and the replacement is moved into place with a rename, so an interrupted write cannot leave a half-file where a running stack's definition used to be.

func (*Manager) StreamEvents

func (m *Manager) StreamEvents(ctx context.Context, hostID int64, onEvent func(EventMsg)) error

StreamEvents forwards live daemon events to onEvent until the context is cancelled or the daemon stream errors. It mirrors the pull/exec streaming pattern so the handler can bridge it straight to a WebSocket.

func (*Manager) StreamLogs

func (m *Manager) StreamLogs(ctx context.Context, hostID int64, id string, follow bool, tail string, emit func(LogLine)) error

StreamLogs tails a container's logs, invoking emit per line. When follow is true it streams until ctx is cancelled; tail bounds the initial backlog.

func (*Manager) StreamStats

func (m *Manager) StreamStats(ctx context.Context, hostID int64, id string, emit func(StatsSample)) error

StreamStats subscribes to a container's stats stream and invokes emit for each computed sample until ctx is cancelled or the stream ends.

func (*Manager) SystemInfo

func (m *Manager) SystemInfo(ctx context.Context, hostID int64) (*SystemInfo, error)

func (*Manager) TagImage

func (m *Manager) TagImage(ctx context.Context, hostID int64, source, target string) error

TagImage adds a new tag (target) to an existing image (source). It is the prerequisite for pushing a local image under a registry-qualified name.

func (*Manager) Topology

func (m *Manager) Topology(ctx context.Context, hostID int64) (*Topology, error)

Topology builds the container↔network connectivity graph for a host.

func (*Manager) UpdateContainer

func (m *Manager) UpdateContainer(ctx context.Context, hostID int64, id string, memory, nanoCPUs int64, restartPolicy string) error

UpdateContainer adjusts a running container's resource limits and restart policy at runtime. Zero values leave the corresponding limit unchanged-as-set.

func (*Manager) UploadExtract added in v1.3.0

func (m *Manager) UploadExtract(ctx context.Context, hostID int64, id, destDir, filename string, body io.Reader) error

UploadExtract streams an archive into destDir, extracting it. The Docker CopyToContainer API takes a TAR and untars it (jailing traversal), so we convert the upload to a TAR stream based on its extension.

func (*Manager) VolumeCopyFrom added in v1.3.0

func (m *Manager) VolumeCopyFrom(ctx context.Context, hostID int64, volume, p string) (io.ReadCloser, container.PathStat, error)

VolumeCopyFrom streams a path out of a volume as a TAR archive.

func (*Manager) VolumeCopyTo added in v1.3.0

func (m *Manager) VolumeCopyTo(ctx context.Context, hostID int64, volume, destDir string, content io.Reader) error

VolumeCopyTo writes a TAR archive into a volume directory.

func (*Manager) VolumeDeletePath added in v1.3.0

func (m *Manager) VolumeDeletePath(ctx context.Context, hostID int64, volume, p string) error

VolumeDeletePath removes a path inside a volume.

func (*Manager) VolumeListPath added in v1.3.0

func (m *Manager) VolumeListPath(ctx context.Context, hostID int64, volume, p string) ([]FileEntry, error)

VolumeListPath lists one directory level inside a volume.

func (*Manager) VolumeMakeDir added in v1.3.0

func (m *Manager) VolumeMakeDir(ctx context.Context, hostID int64, volume, p string) error

VolumeMakeDir creates a directory inside a volume.

func (*Manager) VolumeUploadExtract added in v1.3.0

func (m *Manager) VolumeUploadExtract(ctx context.Context, hostID int64, volume, destDir, filename string, body io.Reader) error

VolumeUploadExtract extracts an archive into a volume directory.

func (*Manager) WatchEvents

func (m *Manager) WatchEvents(ctx context.Context, hostID int64, fn func(Event)) error

WatchEvents streams container events from the host, invoking fn for each, until ctx is cancelled or the stream errors.

type MountInfo

type MountInfo struct {
	Type        string `json:"type"`
	Source      string `json:"source"`
	Destination string `json:"destination"`
	RW          bool   `json:"rw"`
}

MountInfo describes a volume or bind mount.

type NetInterfaceStats added in v1.6.0

type NetInterfaceStats struct {
	Name      string `json:"name"`
	RxBytes   uint64 `json:"rxBytes"`
	TxBytes   uint64 `json:"txBytes"`
	RxPackets uint64 `json:"rxPackets"`
	TxPackets uint64 `json:"txPackets"`
	RxDropped uint64 `json:"rxDropped"`
	TxDropped uint64 `json:"txDropped"`
	RxErrors  uint64 `json:"rxErrors"`
	TxErrors  uint64 `json:"txErrors"`
}

NetInterfaceStats is one container interface's cumulative counters.

type NetworkAttach

type NetworkAttach struct {
	Name       string `json:"name"`
	NetworkID  string `json:"networkId"`
	IPAddress  string `json:"ipAddress"`
	Gateway    string `json:"gateway"`
	MacAddress string `json:"macAddress"`
}

NetworkAttach links a container to a network with its assigned address.

type NetworkCreateRequest added in v1.3.0

type NetworkCreateRequest struct {
	Name       string            `json:"name"`
	Driver     string            `json:"driver"`
	Subnet     string            `json:"subnet"`
	Gateway    string            `json:"gateway"`
	Internal   bool              `json:"internal"`
	Attachable bool              `json:"attachable"`
	Labels     map[string]string `json:"labels"`
}

NetworkCreateRequest holds the user-supplied options for a new network.

type NetworkEndpointStats added in v1.6.0

type NetworkEndpointStats struct {
	ContainerID   string `json:"containerId"`
	ContainerName string `json:"containerName"`
	RxBytes       uint64 `json:"rxBytes"`
	TxBytes       uint64 `json:"txBytes"`
	RxDropped     uint64 `json:"rxDropped"`
	TxDropped     uint64 `json:"txDropped"`
	RxErrors      uint64 `json:"rxErrors"`
	TxErrors      uint64 `json:"txErrors"`
	// Attributable is false when the container is on several networks, so its
	// counters cover all of them and cannot honestly be assigned to this one.
	Attributable bool `json:"attributable"`
}

NetworkEndpointStats is one container's contribution to a network.

type NetworkStats added in v1.6.0

type NetworkStats struct {
	NetworkID string `json:"networkId"`
	// RxBytes/TxBytes total ONLY the attributable endpoints. Labelled "endpoint"
	// deliberately: container-to-container traffic inside a network is counted
	// twice, once as each side's TX and once as its RX, so this is not the volume
	// of traffic on the wire and must never be presented as such.
	RxBytes      uint64 `json:"rxBytes"`
	TxBytes      uint64 `json:"txBytes"`
	RxDropped    uint64 `json:"rxDropped"`
	TxDropped    uint64 `json:"txDropped"`
	RxErrors     uint64 `json:"rxErrors"`
	TxErrors     uint64 `json:"txErrors"`
	Endpoints    int    `json:"endpoints"`
	Unattributed int    `json:"unattributed"`

	Containers []NetworkEndpointStats `json:"containers"`
}

NetworkStats aggregates a network's attached containers.

type NetworkSummary

type NetworkSummary struct {
	ID         string   `json:"id"`
	Name       string   `json:"name"`
	Driver     string   `json:"driver"`
	Scope      string   `json:"scope"`
	Internal   bool     `json:"internal"`
	Subnets    []string `json:"subnets"`
	Containers []string `json:"containers"` // container IDs attached
}

NetworkSummary describes a Docker network for the networks/topology views.

type PolicyMode added in v1.7.0

type PolicyMode string

PolicyMode is how a rule's violation is handled.

const (
	ModeOff   PolicyMode = "off"
	ModeWarn  PolicyMode = "warn"
	ModeBlock PolicyMode = "block"
)

type PolicyRuleID added in v1.7.0

type PolicyRuleID string

PolicyRuleID identifies one deploy-time policy check. The string values are the wire/storage format — duplicated (not imported) in internal/store, since internal/store cannot import this package without creating a cycle (internal/docker already imports internal/store). A cross-package consistency test in internal/api keeps the two lists in sync.

const (
	RulePrivileged         PolicyRuleID = "privileged"
	RuleHostNetwork        PolicyRuleID = "host_network"
	RuleHostPID            PolicyRuleID = "host_pid"
	RuleDockerSocket       PolicyRuleID = "docker_socket_mount"
	RuleLatestTag          PolicyRuleID = "latest_tag"
	RuleMissingLimits      PolicyRuleID = "missing_resource_limits"
	RuleMissingHealthcheck PolicyRuleID = "missing_healthcheck"
)

type PolicyViolation added in v1.7.0

type PolicyViolation struct {
	Rule    PolicyRuleID `json:"rule"`
	Service string       `json:"service"`
	Mode    PolicyMode   `json:"mode"`
	Detail  string       `json:"detail"`
}

PolicyViolation is one rule failing for one service.

func EvaluatePolicy added in v1.7.0

func EvaluatePolicy(configJSON []byte, modes map[PolicyRuleID]PolicyMode) ([]PolicyViolation, error)

EvaluatePolicy checks the resolved compose config (as returned by ComposeConfigJSON) against modes, and returns one PolicyViolation per rule+service that fails a non-off rule. A rule missing from modes defaults to off — fail-safe, so an unrecognised/unset rule never silently blocks a deploy.

type PortMapping

type PortMapping struct {
	IP          string `json:"ip,omitempty"`
	PrivatePort uint16 `json:"privatePort"`
	PublicPort  uint16 `json:"publicPort,omitempty"`
	Type        string `json:"type"`
}

PortMapping describes one published port.

type PortProbe added in v1.1.0

type PortProbe struct {
	PrivatePort uint16 `json:"privatePort"`
	PublicPort  uint16 `json:"publicPort"`
	Type        string `json:"type"` // tcp | udp
	GuessByPort string `json:"guessByPort"`
	Open        bool   `json:"open"`
	Detected    string `json:"detected"`        // active fingerprint, "" if inconclusive
	Info        string `json:"info,omitempty"`  // banner / Server header / TLS subject
	TLS         bool   `json:"tls"`             // a TLS handshake succeeded
	Error       string `json:"error,omitempty"` // why the probe failed (closed/timeout)
}

PortProbe is the result of inspecting one published container port: the passive guess (from the well-known port number) plus the active fingerprint of whatever is actually listening.

type PortSpec

type PortSpec struct {
	HostPort      string `json:"hostPort"`      // empty = expose only, no host binding
	ContainerPort string `json:"containerPort"` // required
	Proto         string `json:"proto"`         // tcp (default) | udp
}

PortSpec is one published port in a create request.

type ProjectBind added in v1.6.0

type ProjectBind struct {
	Service  string // compose service declaring the mount
	Source   string // host path, as compose resolved it (absolute)
	Target   string // path inside the container
	ReadOnly bool
	Rel      string // Source relative to the project dir ("." = the dir itself)
	IsFile   bool   // Source is a regular file rather than a directory
}

ProjectBind is a host-path bind mount from a project's resolved compose config.

func ClassifyProjectBinds added in v1.6.0

func ClassifyProjectBinds(configJSON []byte, projectDir string) (internal, external []ProjectBind, err error)

ClassifyProjectBinds splits the bind mounts in a resolved compose config (`docker compose config --format json`) into those whose source lives inside projectDir — which a remote deploy can ship as a seeded volume — and those that don't, which it must refuse. Symlinks are resolved before the containment test, so a link inside the project pointing out of it counts as external.

func (ProjectBind) String added in v1.6.0

func (b ProjectBind) String() string

String renders a bind for user-facing messages.

type PullProgress

type PullProgress struct {
	Status  string `json:"status,omitempty"`
	ID      string `json:"id,omitempty"`
	Current int64  `json:"current,omitempty"`
	Total   int64  `json:"total,omitempty"`
	Error   string `json:"error,omitempty"`
	Done    bool   `json:"done,omitempty"`
}

PullProgress is one progress update from an image pull, forwarded to the UI.

type ResourceOverview added in v1.1.0

type ResourceOverview struct {
	CPUs       int             `json:"cpus"`
	MemTotal   int64           `json:"memTotal"`
	Containers []ResourceUsage `json:"containers"`
}

ResourceOverview is a snapshot of how the running containers divide up the host's CPU and memory — the data behind the dashboard's usage breakdown.

type ResourceUsage added in v1.1.0

type ResourceUsage struct {
	ID         string  `json:"id"`
	Name       string  `json:"name"`
	CPUPercent float64 `json:"cpuPercent"` // share of total host CPU (0..100)
	MemBytes   uint64  `json:"memBytes"`
	MemPercent float64 `json:"memPercent"` // share of total host memory (0..100)
	// Throughput derived from consecutive monitor polls. Zero until a second
	// sample exists and after a counter reset — there is no honest rate to show
	// for a container that has only just been seen.
	NetRxRate float64 `json:"netRxRate"` // bytes/s
	NetTxRate float64 `json:"netTxRate"` // bytes/s
}

ResourceUsage is one container's live share of the host's CPU and memory.

type ScanResult added in v1.5.0

type ScanResult struct {
	Ref     string          `json:"ref"`
	Summary map[string]int  `json:"summary"` // severity → count
	Vulns   []Vulnerability `json:"vulns"`
}

ScanResult is the parsed outcome of an image scan.

func ScanImage added in v1.5.0

func ScanImage(ctx context.Context, env []string, ref string) (ScanResult, error)

ScanImage scans an image reference for vulnerabilities with Trivy, targeting the daemon described by env (from ComposeHostEnv; nil = local). The ref must pass ValidImageRef. Returns a summary + the vulnerability list.

type SeedSnapshot added in v1.7.0

type SeedSnapshot struct {
	// contains filtered or unexported fields
}

SeedSnapshot is what a project's seed volumes held before they were reseeded, kept on the Docker Commander machine so a restore that fails afterwards can put it back.

Seeding writes into the volumes the running containers mount, under stable names, so a restore that seeded and then failed (a later seed, the file swap, `compose up`) left the containers reading the old revision's files while the API reported a failure. The project folder was rolled back; the volumes were not.

func (*SeedSnapshot) Discard added in v1.7.0

func (s *SeedSnapshot) Discard(_ context.Context)

Discard removes the snapshot's local files. Call it once the restore no longer needs them, whatever the outcome.

func (*SeedSnapshot) Restore added in v1.7.0

func (s *SeedSnapshot) Restore(ctx context.Context) error

Restore puts every snapshotted volume back as it was: its content replaced by the snapshot, owners and modes included, or removed if the restore created it. It carries on past a failing volume and reports every failure, so one volume that can't be restored doesn't leave the others reseeded.

type ServiceChange added in v1.6.0

type ServiceChange struct {
	Service string `json:"service"`
	// Kind is "added" (would be created), "removed" (running but no longer in
	// the file), "image" or "digest" (same service, different image), or one
	// of the extended-comparison kinds from ExtendServiceComparison: "env",
	// "ports", "volumes", "networks", "restart" or "resources"/"healthcheck".
	Kind     string `json:"kind"`
	From     string `json:"from,omitempty"`
	To       string `json:"to,omitempty"`
	Detail   string `json:"detail,omitempty"`
	Existing bool   `json:"existing"`
	// Recreates flags that applying this change means the running container
	// is destroyed and recreated (the downtime-risk callout) — true for
	// everything except "added" (a brand-new container) and "removed" (an
	// orphan a deploy leaves running, untouched).
	Recreates bool `json:"recreates"`
	// Ignored marks a change a human has reviewed and deliberately accepted as
	// ongoing drift (see MarkIgnoredChanges) — still reported, so it stays
	// visible and reversible, but excluded from ActiveChanges.
	Ignored bool `json:"ignored"`
}

ServiceChange is one difference between the resolved config and reality.

type ServicePort added in v1.7.0

type ServicePort struct {
	Target    int    `json:"target"`
	Published string `json:"published,omitempty"`
	Protocol  string `json:"protocol,omitempty"`
}

ServicePort is one published port mapping.

type ServiceSpec added in v1.6.0

type ServiceSpec struct {
	Name  string `json:"name"`
	Image string `json:"image,omitempty"`

	// Detailed is true once the fields below have actually been populated.
	// RunningServices below leaves it false (image only, no extra Docker API
	// calls) — BuildDeployPreview's extended comparisons only run when BOTH
	// sides are Detailed, so a caller that hasn't paid for LiveServiceSpec
	// gets exactly the old add/removed/image-only behaviour.
	Detailed bool `json:"-"`

	Env         map[string]string `json:"env,omitempty"`
	Ports       []ServicePort     `json:"ports,omitempty"`
	Volumes     []VolumeSpec      `json:"volumes,omitempty"`
	Networks    []string          `json:"networks,omitempty"`
	Restart     string            `json:"restart,omitempty"`
	CPULimit    float64           `json:"cpuLimit,omitempty"`
	MemoryLimit int64             `json:"memoryLimit,omitempty"`
	Healthcheck *HealthcheckSpec  `json:"healthcheck,omitempty"`
}

ServiceSpec is one service as compose resolves it, or (when Detailed) as a running container actually has it — see deployfields.go for the extended fields and how the running side is built (LiveServiceSpec).

func ParseComposeServices added in v1.6.0

func ParseComposeServices(configJSON []byte) ([]ServiceSpec, error)

ParseComposeServices pulls the full service list out of `docker compose config --format json` — image plus env/ports/volumes/networks/restart/ resources/healthcheck (see deployfields.go).

func RunningServices added in v1.6.0

func RunningServices(st *Stack) []ServiceSpec

RunningServices reduces a stack's containers to one entry per compose service.

type Stack added in v1.2.0

type Stack struct {
	Project    string           `json:"project"`
	ConfigFile string           `json:"configFile,omitempty"` // host path, from the label
	WorkingDir string           `json:"workingDir,omitempty"`
	Containers []StackContainer `json:"containers"`
	Running    int              `json:"running"`
}

Stack is a group of containers sharing a Compose project label.

type StackComposeView added in v1.7.3

type StackComposeView struct {
	Path    string
	Content string
	// Editable is whether Save can succeed. Redeployable is whether Redeploy can:
	// it needs the same reachable, contained file but no write access, so a file
	// the app can only read still redeploys.
	Editable     bool
	Redeployable bool
	// ReadOnlyReason says why Editable is false, for the UI to show.
	ReadOnlyReason string
}

StackComposeView is a stack's compose file plus what the app may do with it.

type StackContainer added in v1.2.0

type StackContainer struct {
	ID      string        `json:"id"`
	Name    string        `json:"name"`
	Service string        `json:"service"`
	State   string        `json:"state"`
	Status  string        `json:"status"`
	Image   string        `json:"image"`
	Ports   []PortMapping `json:"ports,omitempty"`
}

StackContainer is one container belonging to a Compose stack.

type StatsSample

type StatsSample struct {
	ContainerID string `json:"containerId"`
	Timestamp   int64  `json:"timestamp"` // unix millis
	// CPUPercent uses the `docker stats` convention: 100% is ONE core, so a
	// container busy on four cores reads ~400%. CPUCores carries how many the
	// daemon reported, which is the only way a reader can turn that figure into
	// "how much of this machine" — a distinction that otherwise makes any fixed
	// threshold meaningless on multi-core hosts.
	CPUPercent float64 `json:"cpuPercent"`
	CPUCores   float64 `json:"cpuCores"`
	MemUsage   uint64  `json:"memUsage"`
	MemLimit   uint64  `json:"memLimit"`
	MemPercent float64 `json:"memPercent"`
	// Network counters are CUMULATIVE totals since the container started, summed
	// across its interfaces. Rates are deliberately not computed here: a rate is
	// a function of the sampling interval, so deriving it at read time from two
	// stored counters keeps history honest whatever the interval was — and makes
	// a counter reset (container recreated) visible instead of baked in.
	NetRx        uint64 `json:"netRx"`
	NetTx        uint64 `json:"netTx"`
	NetRxPackets uint64 `json:"netRxPackets"`
	NetTxPackets uint64 `json:"netTxPackets"`
	NetRxDropped uint64 `json:"netRxDropped"`
	NetTxDropped uint64 `json:"netTxDropped"`
	NetRxErrors  uint64 `json:"netRxErrors"`
	NetTxErrors  uint64 `json:"netTxErrors"`
	// Interfaces is the per-interface breakdown. Docker names them eth0, eth1…
	// and does NOT say which Docker network each belongs to — mapping that needs
	// MAC/namespace inspection, which is Linux-only and hostile to remote hosts.
	// So this is reported as-is rather than attributed to a network.
	Interfaces []NetInterfaceStats `json:"interfaces,omitempty"`
	BlkRead    uint64              `json:"blkRead"`
	BlkWrite   uint64              `json:"blkWrite"`
	PIDs       uint64              `json:"pids"`
}

StatsSample is one point in a container's real-time resource time series.

type SystemInfo

type SystemInfo struct {
	HostName        string `json:"hostName"`
	ServerVersion   string `json:"serverVersion"`
	OperatingSystem string `json:"operatingSystem"`
	OSType          string `json:"osType"`
	OSVersion       string `json:"osVersion"`
	KernelVersion   string `json:"kernelVersion"`
	Architecture    string `json:"architecture"`
	CPUs            int    `json:"cpus"`
	MemTotal        int64  `json:"memTotal"`

	StorageDriver string `json:"storageDriver"`
	LoggingDriver string `json:"loggingDriver"`
	CgroupDriver  string `json:"cgroupDriver"`
	CgroupVersion string `json:"cgroupVersion"`
	DockerRootDir string `json:"dockerRootDir"`
	LiveRestore   bool   `json:"liveRestore"`

	Containers        int `json:"containers"`
	ContainersRunning int `json:"containersRunning"`
	ContainersPaused  int `json:"containersPaused"`
	ContainersStopped int `json:"containersStopped"`
	Images            int `json:"images"`
}

SystemInfo summarises the Docker host itself: hardware, OS/kernel and the engine configuration. Note that for Docker Desktop (Windows/macOS) these describe the engine's Linux VM, not the desktop OS — the Docker API does not expose the underlying host, so KernelVersion/OSType are the best hint (e.g. a "…microsoft-standard-WSL2" kernel reveals a Windows/WSL2 host).

type TopResult

type TopResult struct {
	Titles    []string   `json:"titles"`
	Processes [][]string `json:"processes"`
}

TopResult is the process listing inside a container (docker top).

type TopoContainer

type TopoContainer struct {
	ID    string        `json:"id"`
	Name  string        `json:"name"`
	Image string        `json:"image"`
	State string        `json:"state"`
	Stack string        `json:"stack,omitempty"` // compose project, for grouping/filtering
	Ports []PortMapping `json:"ports,omitempty"` // published ports, for the list views
}

TopoContainer is a container node in the topology graph.

type TopoLink struct {
	ContainerID string `json:"containerId"`
	NetworkID   string `json:"networkId"`
	IPAddress   string `json:"ipAddress"`
}

TopoLink is an edge: a container attached to a network with an assigned IP.

type TopoNetwork

type TopoNetwork struct {
	ID       string   `json:"id"`
	Name     string   `json:"name"`
	Driver   string   `json:"driver"`
	Scope    string   `json:"scope"`
	Internal bool     `json:"internal"`
	Subnets  []string `json:"subnets"`
}

TopoNetwork is a network node in the topology graph.

type Topology

type Topology struct {
	Networks   []TopoNetwork   `json:"networks"`
	Containers []TopoContainer `json:"containers"`
	Links      []TopoLink      `json:"links"`
}

Topology is a graph view of how containers attach to networks, consumed by the frontend connectivity diagram.

type UsageCategory

type UsageCategory struct {
	Count int   `json:"count"`
	Size  int64 `json:"size"`
}

UsageCategory is a count + total size for one class of Docker object.

type VolumePruneResult

type VolumePruneResult struct {
	Deleted        []string `json:"deleted"`
	SpaceReclaimed uint64   `json:"spaceReclaimed"`
}

VolumePruneResult reports what an unused-volume prune removed.

type VolumeSpec added in v1.7.0

type VolumeSpec struct {
	Type   string `json:"type"`
	Source string `json:"source,omitempty"`
	Target string `json:"target"`
}

VolumeSpec is one mount. Source is the compose-declared volume name (not project-prefixed) for a named volume, or the absolute host path for a bind.

type VolumeSummary

type VolumeSummary struct {
	Name       string            `json:"name"`
	Driver     string            `json:"driver"`
	Mountpoint string            `json:"mountpoint"`
	Scope      string            `json:"scope"`
	CreatedAt  string            `json:"createdAt"`
	Labels     map[string]string `json:"labels"`
	InUseBy    []string          `json:"inUseBy"` // container names mounting this volume
}

VolumeSummary describes a Docker volume for the Volumes page, including which containers currently mount it so removal is informed.

type Vulnerability added in v1.5.0

type Vulnerability struct {
	ID           string `json:"id"`
	Severity     string `json:"severity"`
	Package      string `json:"package"`
	Version      string `json:"version"`
	FixedVersion string `json:"fixedVersion,omitempty"`
	Title        string `json:"title,omitempty"`
	URL          string `json:"url,omitempty"`
}

Vulnerability is one finding from a scan.

Jump to

Keyboard shortcuts

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