docker

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package docker wraps the Docker Engine API for ah container lifecycle.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnvironmentIngressAlias 

func EnvironmentIngressAlias(tenantID, environmentID string) string

EnvironmentIngressAlias returns a name that resolves only on this environment's dedicated preview ingress network.

func EnvironmentIngressNetworkName 

func EnvironmentIngressNetworkName(tenantID, environmentID string) string

EnvironmentIngressNetworkName returns a network dedicated to one environment with previews and the platform proxy.

func ServiceIngressAlias 

func ServiceIngressAlias(tenantID, serviceID string) string

ServiceIngressAlias returns a name that resolves only on this service's dedicated ingress network.

func ServiceIngressNetworkName 

func ServiceIngressNetworkName(tenantID, serviceID string) string

ServiceIngressNetworkName returns a network dedicated to one tenant service and the platform proxy. Workloads do not share this network with each other.

func TenantIngressNetworkPrefix 

func TenantIngressNetworkPrefix(tenantID string) string

TenantIngressNetworkPrefix returns the prefix for a tenant's per-workload ingress networks, used during tenant cleanup.

func TenantNetworkName 

func TenantNetworkName(tenantID string) string

TenantNetworkName returns the deterministic network name for a tenant.

Types

type Client 

type Client interface {
	EnsureNetwork(ctx context.Context, name string) (string, error)
	EnsureIngressNetwork(ctx context.Context, name string) (string, error)
	ConnectNetwork(ctx context.Context, networkID, containerID string) error
	ConnectNetworkAlias(ctx context.Context, networkID, containerID, alias string) error
	NetworkDisconnect(ctx context.Context, networkID, containerID string) error
	NetworkList(ctx context.Context) ([]NetworkInfo, error)
	NetworkInspect(ctx context.Context, networkID string) (NetworkInfo, error)
	RemoveNetwork(ctx context.Context, networkID string) error
	RunContainer(ctx context.Context, tenantID, serviceID, img string, port int, envVars map[string]string, extraLabels map[string]string, limits *ResourceLimits) (string, error)
	StopContainer(ctx context.Context, containerID string) error
	StartContainer(ctx context.Context, containerID string) error
	RestartContainer(ctx context.Context, containerID string) error
	RemoveContainer(ctx context.Context, containerID string) error
	LogsContainer(ctx context.Context, containerID string, follow bool, tail int) (io.ReadCloser, error)
	InspectContainer(ctx context.Context, containerID string) (*ContainerInfo, error)
	PullImage(ctx context.Context, img string) error
	ImageExists(ctx context.Context, img string) (bool, error)
	TagImage(ctx context.Context, source, target string) error
	RemoveImage(ctx context.Context, imageRef string) error
	ListContainersByLabel(ctx context.Context, label, value string) ([]string, error)
	GetContainerLabels(ctx context.Context, containerID string) map[string]string
	GetContainerName(ctx context.Context, containerID string) string
	VerifyGVisorRuntime(ctx context.Context) error
	CreateVolume(ctx context.Context, name string) error
	RemoveVolume(ctx context.Context, name string) error
	RemoveVolumeSafe(ctx context.Context, name string) error
	WipeVolume(ctx context.Context, name string) error
	RunDatabase(ctx context.Context, cfg RunDatabaseConfig) (string, error)
	StopAndRemoveByName(ctx context.Context, name string) error
	PruneDanglingImages(ctx context.Context) (int, error)
	PruneAnonymousVolumes(ctx context.Context) (int, error)
	ListImages(ctx context.Context) ([]ImageInfo, error)
	ListContainerImages(ctx context.Context) ([]string, error)
	ListNetworkContainers(ctx context.Context, networkName string) ([]string, error)
	ListVolumes(ctx context.Context, prefix string) ([]string, error)
	DiskUsage(ctx context.Context) (*StorageUsage, error)
	RunEnvironment(ctx context.Context, cfg RunEnvironmentConfig) (string, error)
	ExecCreate(ctx context.Context, containerID string, cmd []string, workDir string) (string, error)
	ExecRun(ctx context.Context, execID string, timeout time.Duration) (stdout []byte, stderr []byte, exitCode int, err error)
	RenameContainer(ctx context.Context, containerID, newName string) error
	CopyToContainer(ctx context.Context, containerID string, dstPath string, content io.Reader) error
	ContainerStats(ctx context.Context, containerID string) (*ContainerStats, error)
}

Client is the interface that callers outside this package use to interact with Docker. DockerClient is the production implementation.

type ContainerInfo 

type ContainerInfo struct {
	CreatedAt     time.Time
	Status        string
	StartedAt     string
	ExitCode      int
	HealthStatus  string // "", "starting", "healthy", "unhealthy", "none"
	EffectivePort int
	RestartCount  int // times Docker's restart policy has restarted this container
}

ContainerInfo holds inspected container state.

type ContainerStats 

type ContainerStats struct {
	CPUTotalNanos uint64 // cumulative CPU time since the container started
	MemoryBytes   uint64 // current memory usage
}

ContainerStats is a point-in-time resource reading for one container.

type DockerClient 

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

DockerClient wraps the Docker Engine API client with ah-specific defaults.

func NewClient 

func NewClient() (*DockerClient, error)

NewClient creates a Docker API client using the default socket.

func (*DockerClient) Close 

func (c *DockerClient) Close() error

Close releases the Docker client resources.

func (*DockerClient) ConnectNetwork 

func (c *DockerClient) ConnectNetwork(ctx context.Context, networkID, containerID string) error

ConnectNetwork connects a container to an additional network.

func (*DockerClient) ConnectNetworkAlias 

func (c *DockerClient) ConnectNetworkAlias(ctx context.Context, networkID, containerID, alias string) error

ConnectNetworkAlias attaches a container with a network-scoped DNS alias.

func (*DockerClient) ContainerStats 

func (c *DockerClient) ContainerStats(ctx context.Context, containerID string) (*ContainerStats, error)

ContainerStats takes a single (non-streaming) stats reading.

func (*DockerClient) CopyToContainer 

func (c *DockerClient) CopyToContainer(ctx context.Context, containerID string, dstPath string, content io.Reader) error

CopyToContainer copies a tar archive into the container at dstPath.

func (*DockerClient) CreateVolume 

func (c *DockerClient) CreateVolume(ctx context.Context, name string) error

CreateVolume creates a named Docker volume.

func (*DockerClient) DiskUsage 

func (c *DockerClient) DiskUsage(ctx context.Context) (*StorageUsage, error)

DiskUsage returns aggregate Docker storage consumption by category. Calls the Docker Engine /system/df API.

func (*DockerClient) EnsureIngressNetwork 

func (c *DockerClient) EnsureIngressNetwork(ctx context.Context, name string) (string, error)

EnsureIngressNetwork creates an internal bridge used only by Traefik and one routed workload. ICC is enabled on this dedicated pair network so the proxy can reach the workload; tenant and pool networks retain ICC=false.

func (*DockerClient) EnsureNetwork 

func (c *DockerClient) EnsureNetwork(ctx context.Context, name string) (string, error)

EnsureNetwork creates a Docker network if it doesn't exist. Returns the network ID.

func (*DockerClient) ExecCreate 

func (c *DockerClient) ExecCreate(ctx context.Context, containerID string, cmd []string, workDir string) (string, error)

ExecCreate creates an exec instance in a container. Returns the exec ID.

func (*DockerClient) ExecRun 

func (c *DockerClient) ExecRun(ctx context.Context, execID string, timeout time.Duration) (stdout []byte, stderr []byte, exitCode int, err error)

ExecRun attaches to an exec instance, reads stdout/stderr, and returns the output along with the exit code. Output is capped at 1MB per stream.

func (*DockerClient) GetContainerLabels 

func (c *DockerClient) GetContainerLabels(ctx context.Context, containerID string) map[string]string

GetContainerLabels returns the labels for a container, or nil on error.

func (*DockerClient) GetContainerName 

func (c *DockerClient) GetContainerName(ctx context.Context, containerID string) string

GetContainerName returns the name of a container, or empty string on error.

func (*DockerClient) ImageExists 

func (c *DockerClient) ImageExists(ctx context.Context, img string) (bool, error)

ImageExists reports whether the image is present in the local Docker image store.

func (*DockerClient) InspectContainer 

func (c *DockerClient) InspectContainer(ctx context.Context, containerID string) (*ContainerInfo, error)

InspectContainer returns the container's current state.

func (*DockerClient) ListContainerImages 

func (c *DockerClient) ListContainerImages(ctx context.Context) ([]string, error)

ListContainerImages returns the image ref and image ID of every container, running or stopped.

func (*DockerClient) ListContainersByLabel 

func (c *DockerClient) ListContainersByLabel(ctx context.Context, label, value string) ([]string, error)

ListContainersByLabel lists containers matching a label filter.

func (*DockerClient) ListImages 

func (c *DockerClient) ListImages(ctx context.Context) ([]ImageInfo, error)

ListImages returns all local images with their tags and creation time.

func (*DockerClient) ListNetworkContainers 

func (c *DockerClient) ListNetworkContainers(ctx context.Context, networkName string) ([]string, error)

ListNetworkContainers returns the names of all containers (running or stopped) attached to the named network.

func (*DockerClient) ListVolumes 

func (c *DockerClient) ListVolumes(ctx context.Context, prefix string) ([]string, error)

ListVolumes returns volume names matching the given prefix.

func (*DockerClient) LogsContainer 

func (c *DockerClient) LogsContainer(ctx context.Context, containerID string, follow bool, tail int) (io.ReadCloser, error)

LogsContainer returns a reader for container logs.

func (*DockerClient) NetworkDisconnect 

func (c *DockerClient) NetworkDisconnect(ctx context.Context, networkID, containerID string) error

NetworkDisconnect disconnects a container from a network. Ignores "not connected" errors (idempotent).

func (*DockerClient) NetworkInspect 

func (c *DockerClient) NetworkInspect(ctx context.Context, networkID string) (NetworkInfo, error)

NetworkInspect returns authoritative endpoint membership. Docker Engine's network list response may omit Containers, so callers making ownership or cleanup decisions must inspect the individual network.

func (*DockerClient) NetworkList 

func (c *DockerClient) NetworkList(ctx context.Context) ([]NetworkInfo, error)

NetworkList returns all Docker networks with container counts.

func (*DockerClient) PruneAnonymousVolumes 

func (c *DockerClient) PruneAnonymousVolumes(ctx context.Context) (int, error)

PruneAnonymousVolumes removes unused anonymous volumes (named volumes are kept).

func (*DockerClient) PruneDanglingImages 

func (c *DockerClient) PruneDanglingImages(ctx context.Context) (int, error)

PruneDanglingImages removes dangling (untagged, unreferenced) images. Returns the number of images removed.

func (*DockerClient) PullImage 

func (c *DockerClient) PullImage(ctx context.Context, img string) error

PullImage pulls an image with a 5-minute timeout.

func (*DockerClient) RemoveContainer 

func (c *DockerClient) RemoveContainer(ctx context.Context, containerID string) error

RemoveContainer force-removes a container and its anonymous volumes. Named volumes (databases, environments) are not affected.

func (*DockerClient) RemoveImage 

func (c *DockerClient) RemoveImage(ctx context.Context, imageRef string) error

RemoveImage removes an image by reference. Used to clean up snapshot tags.

func (*DockerClient) RemoveNetwork 

func (c *DockerClient) RemoveNetwork(ctx context.Context, networkID string) error

RemoveNetwork removes a Docker network by ID or name.

func (*DockerClient) RemoveVolume 

func (c *DockerClient) RemoveVolume(ctx context.Context, name string) error

RemoveVolume removes a named Docker volume (force).

func (*DockerClient) RemoveVolumeSafe 

func (c *DockerClient) RemoveVolumeSafe(ctx context.Context, name string) error

RemoveVolumeSafe removes a named Docker volume without force. This will fail if the volume is still in use by a container, which is the desired behavior for GC — we never want to force-remove a volume that might be attached to a running container.

func (*DockerClient) RenameContainer 

func (c *DockerClient) RenameContainer(ctx context.Context, containerID, newName string) error

RenameContainer renames a container.

func (*DockerClient) RestartContainer 

func (c *DockerClient) RestartContainer(ctx context.Context, containerID string) error

RestartContainer restarts a container (stop with 10s timeout, then start).

func (*DockerClient) RunContainer 

func (c *DockerClient) RunContainer(ctx context.Context, tenantID, serviceID, img string, port int, envVars map[string]string, extraLabels map[string]string, limits *ResourceLimits) (string, error)

RunContainer creates and starts a container with gVisor runtime.

Network isolation architecture:

  • Container is placed on a per-tenant internal Docker network (Internal=true, ICC=false).
  • A separate internal network connects only this service and Traefik for ingress.
  • Other workloads are not attached to that service ingress network.
  • Cross-tenant isolation: each tenant has a separate bridge network.
  • Defense-in-depth: gVisor (runsc) runtime, CapDrop ALL, no-new-privileges, ReadonlyRootfs, PidsLimit, MemorySwap=Memory (no swap).
  • Health checks are left to the image author; ah does not inject a shell probe because many minimal images do not ship curl/wget.

func (*DockerClient) RunDatabase 

func (c *DockerClient) RunDatabase(ctx context.Context, cfg RunDatabaseConfig) (string, error)

RunDatabase creates and starts a container with host port mapping and persistent volume. Uses gVisor (runsc) runtime. Bound to 127.0.0.1 only. Used for databases and other infrastructure containers (e.g. Vikunja kanban).

func (*DockerClient) RunEnvironment 

func (c *DockerClient) RunEnvironment(ctx context.Context, cfg RunEnvironmentConfig) (string, error)

RunEnvironment creates and starts an environment container with gVisor runtime. Environments are dev workspaces: writable rootfs, sleep infinity entrypoint, workspace volume at /workspace.

func (*DockerClient) StartContainer 

func (c *DockerClient) StartContainer(ctx context.Context, containerID string) error

StartContainer starts a stopped container.

func (*DockerClient) StopAndRemoveByName 

func (c *DockerClient) StopAndRemoveByName(ctx context.Context, name string) error

StopAndRemoveByName stops and removes a container by its name. Returns nil if the container doesn't exist.

func (*DockerClient) StopContainer 

func (c *DockerClient) StopContainer(ctx context.Context, containerID string) error

StopContainer stops a running container with a 10s timeout.

func (*DockerClient) TagImage 

func (c *DockerClient) TagImage(ctx context.Context, source, target string) error

TagImage adds a new tag to an existing image.

func (*DockerClient) VerifyGVisorRuntime 

func (c *DockerClient) VerifyGVisorRuntime(ctx context.Context) error

VerifyGVisorRuntime checks that the Docker daemon has the gVisor (runsc) runtime available.

func (*DockerClient) WipeVolume 

func (c *DockerClient) WipeVolume(ctx context.Context, name string) error

WipeVolume overwrites all files in the named volume with zeros (bounded to each file's own size) in a short-lived sandboxed busybox container, so a future tenant cannot recover deleted data. On ctx expiry the container is killed and removed.

type ImageInfo 

type ImageInfo struct {
	ID      string
	Tags    []string
	Created time.Time
}

ImageInfo describes a local image.

type NetworkInfo 

type NetworkInfo struct {
	ID             string
	Name           string
	Containers     int // number of containers connected to this network
	ContainerNames []string
	Created        time.Time
}

NetworkInfo holds metadata about a Docker network.

type ResourceLimits 

type ResourceLimits struct {
	MemoryMB int64
	CPUCores float64
}

ResourceLimits holds per-container resource constraints from tenant quotas.

type RunDatabaseConfig 

type RunDatabaseConfig struct {
	Name          string
	Image         string
	HostPort      int
	ContainerPort int
	Env           map[string]string
	Cmd           []string
	VolumeName    string
	MountPath     string
	Labels        map[string]string // optional: overrides default labels when set
	User          string            // optional: container user (e.g. "0:0")
}

RunDatabaseConfig holds parameters for running a database container.

type RunEnvironmentConfig 

type RunEnvironmentConfig struct {
	TenantID    string
	EnvID       string
	Image       string
	MemoryMB    int64
	CPUMillis   int64
	VolumeName  string
	NetworkName string
	Labels      map[string]string
	EgressAllow bool
	WarmPool    bool // explicit lifecycle marker for containers created for the warm pool
}

RunEnvironmentConfig holds parameters for running an environment container.

type StorageUsage 

type StorageUsage struct {
	ImagesSize     int64 `json:"images_size_bytes"`
	ContainersSize int64 `json:"containers_size_bytes"`
	VolumesSize    int64 `json:"volumes_size_bytes"`
	BuildCacheSize int64 `json:"build_cache_size_bytes"`
}

StorageUsage holds aggregate Docker storage consumption broken down by type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.