docker

package
v0.4.0-beta.3 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddNetworkToCompose added in v0.1.5 

func AddNetworkToCompose(content string, networkName string) (string, error)

func AddVolumeToService added in v0.1.5 

func AddVolumeToService(content string, serviceName string, volumeMount string) (string, error)

AddVolumeToService adds a volume mount to a specific service in the compose file

func ContainerNameForService 

func ContainerNameForService(content, deploymentName, service string) string

ContainerNameForService returns the DNS-resolvable container name for a service in a deployment, matching what EnsureContainerNames assigns. An explicit container_name in the compose wins; otherwise the EnsureContainerNames rule applies (primary service -> deploymentName, all others -> "{deploymentName}-{service}"). When the compose cannot be parsed it falls back to the deployment-scoped name so the upstream is never the bare, collision-prone service name shared across deployments.

func EnsureContainerNames added in v0.1.5 

func EnsureContainerNames(content string, deploymentName string) (string, error)

EnsureContainerNames ensures all services have explicit container_name set. The primary service (preferring "app") gets deploymentName as its container name. All other services get "{deploymentName}-{serviceName}". Existing container_name values are preserved.

func EnsureServiceEnvFile 

func EnsureServiceEnvFile(content, envFile string) (string, error)

EnsureServiceEnvFile makes every service load envFile, so env written there (e.g. an attached object store's connection details) actually reaches the containers. An existing env_file (string or list form) is preserved and envFile appended only when missing.

func ExecuteService added in v0.1.5 

func ExecuteService(cfg *config.ServiceExecConfig, args []string) ([]byte, error)

func ExtractBindMounts added in v0.1.5 

func ExtractBindMounts(composeContent string) []string

ExtractBindMounts parses compose content and returns bind mount host paths.

func ExtractFileFromImage added in v0.3.0 

func ExtractFileFromImage(image, path string) ([]byte, error)

ExtractFileFromImage reads a single file from a container image without running it, by creating a stopped container and copying the file out. Missing images are pulled, so the call is bounded by a timeout.

func FindComposeFile 

func FindComposeFile(dirPath string) string

FindComposeFile returns the path to the compose file in dirPath, preferring the standard filenames and falling back to a *compose*.yml/yaml glob. Returns "" when none.

func FindVolumeMount 

func FindVolumeMount(content, serviceName, hostPath, containerPath string) (string, bool)

RemoveVolumeFromService removes a volume mount from a specific service in the compose file FindVolumeMount returns a service's volume entry whose host and container sides match, ignoring trailing options such as ":ro". Removal matches the entry's exact text, so a caller that knows only what a mount connects can use this to address it.

func GetDeploymentResources added in v0.1.5 

func GetDeploymentResources(projectName string) (map[string]*ResourceLimits, error)

func HasVolumeMount added in v0.1.5 

func HasVolumeMount(content string, serviceName string, volumeMount string) bool

HasVolumeMount checks if a service has a specific volume mount

func InspectContainerUser added in v0.1.5 

func InspectContainerUser(containerName string) (string, error)

InspectContainerUser gets the UID:GID of the running process inside a container.

func MarshalComposeYAML added in v0.1.5 

func MarshalComposeYAML(compose map[string]interface{}) ([]byte, error)

func ParseComposeYAML added in v0.1.5 

func ParseComposeYAML(content string) (map[string]interface{}, error)

func RemoveVolumeFromService added in v0.1.5 

func RemoveVolumeFromService(content string, serviceName string, volumeMount string) (string, error)

func UpdateContainerResources added in v0.1.5 

func UpdateContainerResources(containerID string, update *ResourceUpdate) error

Types

type APIClient added in v0.1.5 

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

func NewAPIClient added in v0.1.5 

func NewAPIClient() (*APIClient, error)

func (*APIClient) Close added in v0.1.5 

func (a *APIClient) Close() error

func (*APIClient) ContainerPrimaryIP 

func (a *APIClient) ContainerPrimaryIP(ctx context.Context, project, network string) (string, error)

ContainerPrimaryIP returns the IP address of a project's first running container on the given docker network. The agent runs on the host, so a service that only exposes ports on an internal compose network (a self-hosted object store, say) is reached by dialing the container's address directly. When network is empty, the first attached network with an address is used.

func (*APIClient) CopyPathToHost 

func (a *APIClient) CopyPathToHost(ctx context.Context, containerID, containerPath, hostPath string) error

CopyPathToHost writes containerPath from an existing container out to hostPath. The container does not need to be running, so a caller can stop it first and be certain the copy cannot miss a later write.

func (*APIClient) EnsureImage 

func (a *APIClient) EnsureImage(ctx context.Context, ref string) error

EnsureImage makes an image available locally, pulling it only when it is absent so a seeded deploy of an already-pulled image costs nothing.

func (*APIClient) ExecInContainer added in v0.1.5 

func (a *APIClient) ExecInContainer(ctx context.Context, containerID string, command string) (string, error)

func (*APIClient) ExecInService added in v0.1.5 

func (a *APIClient) ExecInService(ctx context.Context, project, service, command string) (string, error)

func (*APIClient) FindContainer added in v0.1.5 

func (a *APIClient) FindContainer(ctx context.Context, project, service string) (string, error)

func (*APIClient) ListContainerPath 

func (a *APIClient) ListContainerPath(ctx context.Context, containerID, dir string) ([]ContainerFile, error)

ListContainerPath lists a directory inside a running container.

The Engine API can stat a path and archive it, but cannot list a directory, so this asks the container itself. That means an image with no shell, such as a distroless or scratch build, cannot be browsed; its paths can still be copied out by naming them directly.

func (*APIClient) ListLiveComposeContainers 

func (a *APIClient) ListLiveComposeContainers(ctx context.Context) ([]container.Summary, error)

ListLiveComposeContainers returns the containers of every compose project on the host in a single call.

It deliberately excludes stopped containers, mirroring `compose ps`, which reports only live ones unless asked for all. Including them would both change what callers report and cost noticeably more, since the daemon walks every container a host has ever left behind.

func (*APIClient) ListServiceContainers added in v0.1.5 

func (a *APIClient) ListServiceContainers(ctx context.Context, project string) ([]container.Summary, error)

func (*APIClient) ListServicePath 

func (a *APIClient) ListServicePath(ctx context.Context, project, service, dir string) ([]ContainerFile, error)

ListServicePath lists a directory inside a compose service's running container.

func (*APIClient) SeedFromImage 

func (a *APIClient) SeedFromImage(ctx context.Context, ref, containerPath, hostPath string) error

SeedFromImage copies containerPath out of an image and writes it to hostPath. It suits a deployment that has no container yet; for one that is already running, copy from the container instead, since an image holds nothing an entrypoint generated at runtime.

The container is created but never started: copying reads the image's filesystem, so nothing from the image is executed to seed a host path.

type CleanupResult added in v0.3.0 

type CleanupResult struct {
	Removed    []RemovedImage `json:"removed"`
	FreedBytes int64          `json:"freed_bytes"`
	ImagesKept int            `json:"images_kept"`
	DryRun     bool           `json:"dry_run,omitempty"`
}

type ComposeExecutor 

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

func NewComposeExecutor 

func NewComposeExecutor(basePath string) *ComposeExecutor

func (*ComposeExecutor) Down 

func (c *ComposeExecutor) Down(deploymentPath string, opts ...RunOption) (string, error)

func (*ComposeExecutor) ExecCommand added in v0.1.5 

func (c *ComposeExecutor) ExecCommand(containerID string, command string) (string, error)

func (*ComposeExecutor) GetImageInfo added in v0.1.5 

func (c *ComposeExecutor) GetImageInfo(deploymentPath string) ([]ImageInfo, error)

func (*ComposeExecutor) GetStatus 

func (c *ComposeExecutor) GetStatus(deploymentPath string) (string, error)

func (*ComposeExecutor) Logs 

func (c *ComposeExecutor) Logs(deploymentPath string, tail int) (string, error)

func (*ComposeExecutor) PS 

func (c *ComposeExecutor) PS(deploymentPath string) (string, error)

func (*ComposeExecutor) Pull 

func (c *ComposeExecutor) Pull(deploymentPath string, onlyLatest bool, opts ...RunOption) (string, error)

func (*ComposeExecutor) PullService added in v0.3.0 

func (c *ComposeExecutor) PullService(deploymentPath, service string, opts ...RunOption) (string, error)

func (*ComposeExecutor) Rebuild added in v0.1.5 

func (c *ComposeExecutor) Rebuild(deploymentPath string, opts ...RunOption) (string, error)

func (*ComposeExecutor) RebuildService added in v0.3.0 

func (c *ComposeExecutor) RebuildService(deploymentPath, service string, opts ...RunOption) (string, error)

func (*ComposeExecutor) Restart 

func (c *ComposeExecutor) Restart(deploymentPath string, opts ...RunOption) (string, error)

func (*ComposeExecutor) RestartService added in v0.3.0 

func (c *ComposeExecutor) RestartService(deploymentPath, service string, opts ...RunOption) (string, error)

func (*ComposeExecutor) Start 

func (c *ComposeExecutor) Start(deploymentPath string, opts ...RunOption) (string, error)

func (*ComposeExecutor) StartService added in v0.3.0 

func (c *ComposeExecutor) StartService(deploymentPath, service string, opts ...RunOption) (string, error)

func (*ComposeExecutor) Stop 

func (c *ComposeExecutor) Stop(deploymentPath string, opts ...RunOption) (string, error)

func (*ComposeExecutor) StopService added in v0.3.0 

func (c *ComposeExecutor) StopService(deploymentPath, service string, opts ...RunOption) (string, error)

func (*ComposeExecutor) StreamLogs 

func (c *ComposeExecutor) StreamLogs(ctx context.Context, deploymentPath string, tail int, sink func(string)) error

StreamLogs follows a deployment's logs, handing each line to sink as it arrives, until ctx is cancelled or the deployment stops producing.

Reading logs as a `--tail` blob means a viewer only knows what was true when it asked, so a user watching a container start reloads to see the next line. Following gives them the line when the container writes it, and cancelling ctx stops the process rather than leaving it attached for the life of the agent.

func (*ComposeExecutor) Up 

func (c *ComposeExecutor) Up(deploymentPath string, opts ...RunOption) (string, error)

type ContainerFile 

type ContainerFile struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	Size        int64  `json:"size"`
	Mode        string `json:"mode"`
	IsDir       bool   `json:"is_dir"`
	IsSymlink   bool   `json:"is_symlink"`
	LinkTarget  string `json:"link_target,omitempty"`
	ModifiedRaw string `json:"modified_raw,omitempty"`
}

ContainerFile is one entry of a directory inside a container.

type ContainerStats added in v0.1.5 

type ContainerStats struct {
	ContainerID    string  `json:"container_id"`
	Name           string  `json:"name"`
	DeploymentName string  `json:"deployment_name,omitempty"`
	CPUPercent     float64 `json:"cpu_percent"`
	MemoryUsage    uint64  `json:"memory_usage"`
	MemoryLimit    uint64  `json:"memory_limit"`
	MemoryPercent  float64 `json:"memory_percent"`
	NetworkRx      uint64  `json:"network_rx"`
	NetworkTx      uint64  `json:"network_tx"`
	BlockRead      uint64  `json:"block_read"`
	BlockWrite     uint64  `json:"block_write"`
	PIDs           int     `json:"pids"`
}

func GetAllContainerStats added in v0.1.5 

func GetAllContainerStats() ([]ContainerStats, error)

func GetContainerStats added in v0.1.5 

func GetContainerStats(containerID string) (*ContainerStats, error)

func GetDeploymentStats added in v0.1.5 

func GetDeploymentStats(projectName string) ([]ContainerStats, error)

type DeploymentStats 

type DeploymentStats struct {
	TotalDeployments int       `json:"total_deployments"`
	Running          int       `json:"running"`
	Stopped          int       `json:"stopped"`
	Error            int       `json:"error"`
	Unknown          int       `json:"unknown"`
	LastUpdated      time.Time `json:"last_updated"`
}

type Discovery 

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

func NewDiscovery 

func NewDiscovery(basePath string) *Discovery

func (*Discovery) ApplyMountOwnership added in v0.1.5 

func (d *Discovery) ApplyMountOwnership(deploymentPath string, mounts []MountOwnership) error

ApplyMountOwnership sets ownership and creates subdirectories for bind mounts. When User is specified (UID:GID format), the mount is chowned recursively to that user so intermediate directories and pre-existing content end up owned by the container too. When User is empty, directories are chmod'd to 0777 as a fallback for non-template deploys. A host path that already exists as a regular file (e.g. a generated .env) is only chowned, never turned into a directory.

func (*Discovery) CreateDeployment 

func (d *Discovery) CreateDeployment(name string, composeContent string, fileMounts []string) error

func (*Discovery) CreateDeploymentFromSource 

func (d *Discovery) CreateDeploymentFromSource(name, srcDir, composeContent, composeName string) error

CreateDeploymentFromSource creates a deployment whose files come from a fetched source tree rather than a single compose string. The whole tree is copied into the deployment directory (so code, not just compose, is preserved), then the transformed compose content is written back over the source's own compose file under composeName, keeping the source's layout. Bind mount directories are created as for a plain compose deployment.

func (*Discovery) DeleteDeployment 

func (d *Discovery) DeleteDeployment(name string) error

func (*Discovery) DeleteMetadata 

func (d *Discovery) DeleteMetadata(name string) error

func (*Discovery) FindDeployments 

func (d *Discovery) FindDeployments() ([]models.Deployment, error)

func (*Discovery) FindInfrastructure added in v0.1.5 

func (d *Discovery) FindInfrastructure() ([]models.Deployment, error)

func (*Discovery) GetComposeFile 

func (d *Discovery) GetComposeFile(name string) (string, string, error)

func (*Discovery) GetDeployment 

func (d *Discovery) GetDeployment(name string) (*models.Deployment, error)

func (*Discovery) SaveMetadata 

func (d *Discovery) SaveMetadata(name string, metadata *models.ServiceMetadata) error

func (*Discovery) UpdateComposeFile 

func (d *Discovery) UpdateComposeFile(name string, content string) error

type ImageInfo added in v0.1.5 

type ImageInfo struct {
	Service  string `json:"service"`
	Image    string `json:"image"`
	IsLatest bool   `json:"is_latest"`
	IsBuild  bool   `json:"is_build"`
}

type Manager 

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

func NewManager 

func NewManager(deploymentsPath string) *Manager

func (*Manager) ApplyMountOwnership added in v0.1.5 

func (m *Manager) ApplyMountOwnership(name string, mounts []MountOwnership) error

func (*Manager) BasePath 

func (m *Manager) BasePath() string

func (*Manager) CleanupDeploymentImages added in v0.3.0 

func (m *Manager) CleanupDeploymentImages(name string, dryRun bool) (CleanupResult, error)

func (*Manager) CleanupTimeout added in v0.3.0 

func (m *Manager) CleanupTimeout() time.Duration

func (*Manager) ComposeExec added in v0.1.5 

func (m *Manager) ComposeExec(ctx context.Context, name string, service string, command string) (string, error)

func (*Manager) ComposeProject 

func (m *Manager) ComposeProject(name string) (string, error)

ComposeProject returns the project name a deployment's containers are labelled with, which is what addresses them on the engine.

func (*Manager) ContainerPrimaryIP 

func (m *Manager) ContainerPrimaryIP(project, network string) (string, error)

ContainerPrimaryIP returns the first running container's address for a deployment on the given docker network. A flatrun deploy names its compose project after the deployment, so the project name is the deployment name.

func (*Manager) CreateDeployment 

func (m *Manager) CreateDeployment(name string, composeContent string, fileMounts []string) error

func (*Manager) CreateDeploymentFromSource 

func (m *Manager) CreateDeploymentFromSource(name, srcDir, composeContent, composeName string) error

func (*Manager) DeleteDeployment 

func (m *Manager) DeleteDeployment(name string) error

func (*Manager) ExecuteQuickAction added in v0.1.5 

func (m *Manager) ExecuteQuickAction(name string, actionID string) (string, error)

func (*Manager) FindDeployments 

func (m *Manager) FindDeployments() ([]models.Deployment, error)

FindDeployments returns deployments built from their on-disk metadata alone, leaving Status unread. Callers that only need names, paths or metadata should prefer it over ListDeployments so they never pay for a Docker round-trip.

func (*Manager) GetComposeFile 

func (m *Manager) GetComposeFile(name string) (string, string, error)

func (*Manager) GetComposeServiceNames added in v0.1.5 

func (m *Manager) GetComposeServiceNames(name string) ([]string, error)

func (*Manager) GetComposeServices added in v0.1.5 

func (m *Manager) GetComposeServices(name string) ([]models.Service, error)

func (*Manager) GetDeployment 

func (m *Manager) GetDeployment(name string) (*models.Deployment, error)

func (*Manager) GetDeploymentImages added in v0.1.5 

func (m *Manager) GetDeploymentImages(name string) ([]ImageInfo, error)

func (*Manager) GetDeploymentLogs 

func (m *Manager) GetDeploymentLogs(name string, tail int) (string, error)

func (*Manager) GetStats 

func (m *Manager) GetStats() (*DeploymentStats, error)

func (*Manager) ListDeployments 

func (m *Manager) ListDeployments() ([]models.Deployment, error)

func (*Manager) ListInfrastructure added in v0.1.5 

func (m *Manager) ListInfrastructure() ([]models.Deployment, error)

func (*Manager) ListServiceFiles 

func (m *Manager) ListServiceFiles(ctx context.Context, project, service, dir string) ([]ContainerFile, error)

ListServiceFiles lists a directory inside a running service's container.

func (*Manager) MaterializeMount 

func (m *Manager) MaterializeMount(name, service, containerPath, hostPath string) error

MaterializeMount copies a path out of a running service's container onto the host, then mounts the host copy back at the same place and brings the service up again.

The order matters. A bind mount pushes the host's content into the container, so mounting a path the container populated would hide it. Copying first means the service resumes on exactly the content it was already running, now visible and editable on the host. The service is stopped before the copy so no write can land between the copy and the mount taking effect and be lost.

func (*Manager) PruneDanglingImages added in v0.3.0 

func (m *Manager) PruneDanglingImages(dryRun bool) (CleanupResult, error)

func (*Manager) PullDeployment added in v0.1.5 

func (m *Manager) PullDeployment(name string, onlyLatest bool, opts ...RunOption) (string, error)

func (*Manager) PullService added in v0.3.0 

func (m *Manager) PullService(name, service string, opts ...RunOption) (string, error)

func (*Manager) RebuildDeployment added in v0.1.5 

func (m *Manager) RebuildDeployment(name string, opts ...RunOption) (string, error)

func (*Manager) RebuildService added in v0.3.0 

func (m *Manager) RebuildService(name, service string, opts ...RunOption) (string, error)

func (*Manager) ResolveService added in v0.1.5 

func (m *Manager) ResolveService(name string, serviceName string) (string, error)

func (*Manager) RestartDeployment 

func (m *Manager) RestartDeployment(name string, opts ...RunOption) (string, error)

func (*Manager) RestartService added in v0.3.0 

func (m *Manager) RestartService(name, service string, opts ...RunOption) (string, error)

func (*Manager) SaveMetadata 

func (m *Manager) SaveMetadata(name string, metadata *models.ServiceMetadata) error

func (*Manager) SeedMounts 

func (m *Manager) SeedMounts(name string, hostPaths []string) error

SeedMounts fills the named bind mounts of a deployment that has not started yet with the content its images hold at those paths.

It suits a deployment with no container to copy from. An image holds nothing an entrypoint generates on first start, so an already-running deployment is better served by copying the container itself.

Only mounts named by the caller are seeded, and only where the host side is still missing or empty, so seeding never overwrites content a user has.

func (*Manager) SetCleanupTimeout added in v0.3.0 

func (m *Manager) SetCleanupTimeout(d time.Duration)

func (*Manager) StartDeployment 

func (m *Manager) StartDeployment(name string, opts ...RunOption) (string, error)

func (*Manager) StartService added in v0.3.0 

func (m *Manager) StartService(name, service string, opts ...RunOption) (string, error)

func (*Manager) StopDeployment 

func (m *Manager) StopDeployment(name string, opts ...RunOption) (string, error)

func (*Manager) StopService added in v0.3.0 

func (m *Manager) StopService(name, service string, opts ...RunOption) (string, error)

func (*Manager) StreamDeploymentLogs 

func (m *Manager) StreamDeploymentLogs(ctx context.Context, name, path string, tail int, sink func(string)) error

StreamDeploymentLogs follows a deployment's logs until ctx is done, handing each line to sink as the container writes it.

The deployment path is passed in rather than looked up again: the caller has already read the deployment, and following holds for as long as someone is watching, which is far too long to hold the manager's lock.

func (*Manager) UnmountPath 

func (m *Manager) UnmountPath(name, service, hostPath, containerPath string) error

UnmountPath removes a bind mount from a service and recreates it, so the service goes back to whatever its image holds at that path.

The recreate is what makes the unmount real. Dropping the mount from the compose file alone leaves the running container still bound to the host, so the host copy would keep reaching into it.

The host copy is left on disk. It is the only place the mounted content exists, and the service no longer reads it, so deleting it is a separate decision for the caller to make deliberately.

func (*Manager) UpdateDeployment 

func (m *Manager) UpdateDeployment(name string, composeContent string) error

type MountOwnership added in v0.1.5 

type MountOwnership struct {
	HostPath       string
	User           string // "UID:GID" or empty
	Subdirectories []string
}

MountOwnership describes ownership and subdirectory requirements for a bind mount.

type RemovedImage added in v0.3.0 

type RemovedImage struct {
	ID    string `json:"id"`
	Tag   string `json:"tag,omitempty"`
	Bytes int64  `json:"bytes"`
}

type ResourceLimits added in v0.1.5 

type ResourceLimits struct {
	MemoryLimit   int64   `json:"memory_limit"`
	MemorySwap    int64   `json:"memory_swap"`
	CPUs          float64 `json:"cpus"`
	CPUShares     int64   `json:"cpu_shares"`
	RestartPolicy string  `json:"restart_policy"`
}

func GetContainerResources added in v0.1.5 

func GetContainerResources(containerID string) (*ResourceLimits, error)

type ResourceUpdate added in v0.1.5 

type ResourceUpdate struct {
	MemoryLimit *int64   `json:"memory_limit,omitempty"`
	MemorySwap  *int64   `json:"memory_swap,omitempty"`
	CPUs        *float64 `json:"cpus,omitempty"`
	CPUShares   *int64   `json:"cpu_shares,omitempty"`
}

type RunOption added in v0.2.0 

type RunOption func(*runOpts)

func WithDockerConfig added in v0.2.0 

func WithDockerConfig(dir string) RunOption

func WithForceRecreate 

func WithForceRecreate() RunOption

WithForceRecreate recreates containers even when their config and image are unchanged, so updated environment variables take effect.

func WithFreshPull 

func WithFreshPull() RunOption

WithFreshPull forces images to be pulled rather than served from the local cache during an up.

func WithLineSink 

func WithLineSink(sink func(string)) RunOption

WithLineSink streams the compose command's combined output to sink one line at a time as it is produced, instead of returning it only on completion.

func WithNoCache 

func WithNoCache() RunOption

WithNoCache rebuilds images without using the build cache before bringing the deployment up.

type ServiceExecutor added in v0.1.5 

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

func NewServiceExecutor added in v0.1.5 

func NewServiceExecutor(cfg *config.ServiceExecConfig) *ServiceExecutor

func (*ServiceExecutor) Execute added in v0.1.5 

func (e *ServiceExecutor) Execute(args []string) ([]byte, error)

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.