docker

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 42 Imported by: 0

Documentation

Overview

Package docker runs donkey's apps straight on a Docker engine — no Kubernetes, no kind. Spaces are user-defined networks (apps of a space reach each other by plain container DNS), apps and provisioned services are containers with donkey labels, disks are named volumes, and the small records Kubernetes keeps in Secrets and ConfigMaps (env, bindings, route table entries, app metadata) live as YAML files in a state directory — a named volume shared with the donkey gateway, whose routing table is exactly the routes/ folder (and whose issued certificates live next to it).

Index

Constants

View Source
const (
	RoleServer           = "server"
	RoleOrchestrator     = "orchestrator"
	RoleGateway          = "gateway"
	RoleAI               = "ai"
	RoleProxy            = "proxy"
	RoleTelemetry        = "telemetry"
	RolePackages         = "packages"
	RoleBuildkit         = "buildkitd"
	RoleRegistry         = "registry"
	RoleNetwork          = "network"
	RoleStateStorage     = "state-storage"
	RoleBuildkitStorage  = "buildkit-storage"
	RoleTelemetryStorage = "telemetry-storage"
	RoleRegistryStorage  = "registry-storage"
)

System role values, shared by the direct Docker installer, generated Compose bundles and the runtime's own checks. One constant per resource: the ownership preflights compare these exactly, so a value spelled twice is a re-install that refuses its own resources.

Variables

This section is empty.

Functions

func AttachOwnContainers

func AttachOwnContainers(ctx context.Context, cli *client.Client, names ...string) error

AttachOwnContainers connects donkey's own containers to every space network that already exists.

Recreating a container drops every network it was attached to, and an install recreates both of donkey's. Docker's embedded DNS only answers for networks the asking container is on, so without this a re-install leaves the gateway unable to resolve any app deployed before it — every existing app stops answering until it happens to be redeployed. ensureSpace does the same thing for one new space; this covers the ones already there.

func IdentityLabelKeys

func IdentityLabelKeys() []string

IdentityLabelKeys is the immutable ownership vocabulary in comparison order — what sameIdentity checks, exported for generated bundles whose shell preflight re-implements that comparison with `docker inspect`.

func MatchesSystemLabels

func MatchesSystemLabels(actual map[string]string, role string) bool

MatchesSystemLabels reports whether labels describe exactly one donkey control-plane resource. Tenant dimensions must be absent: an app resource does not become installation infrastructure merely by carrying the three system labels as well.

func ReadGatewayPolicies

func ReadGatewayPolicies(dir string) (map[string]config.SpaceConfig, config.PlatformConfig, error)

ReadGatewayPolicies reads only the shared state volume; the gateway does not need Docker daemon access to enforce current space membership.

func ReadRecordFile

func ReadRecordFile(path string) ([]byte, error)

ReadRecordFile reads a record by file path, for readers outside the provider (the service proxy's configuration): a path ending in .yaml or .json names the record, read with the same YAML-first fallback. Any other path is read as it is.

func SystemLabels

func SystemLabels(role string) map[string]string

SystemLabels is the ownership/role vocabulary shared by the direct Docker installer, generated Compose bundles, and runtime-created resources.

func SystemRoleOf

func SystemRoleOf(containerName string) string

SystemRoleOf is the naming rule for control-plane containers: the container donkey-<role> carries that role label. The constants above and every donkey-* container name are chosen to satisfy it.

func WriteSystemRoute

func WriteSystemRoute(stateDir, name string, r Route) error

WriteSystemRoute records a route donkey's installer owns (the console).

Types

type GatewayAdapter

type GatewayAdapter struct{ StateDir string }

func (*GatewayAdapter) GatewayCA

func (g *GatewayAdapter) GatewayCA(ctx context.Context, create func() ([]byte, []byte, error)) ([]byte, []byte, error)

func (*GatewayAdapter) GatewayCertificateCache

func (g *GatewayAdapter) GatewayCertificateCache() autocert.Cache

func (*GatewayAdapter) GatewaySnapshot

func (g *GatewayAdapter) GatewaySnapshot(ctx context.Context) (rt.GatewaySnapshot, error)

func (*GatewayAdapter) PrepareGateway

func (g *GatewayAdapter) PrepareGateway(context.Context) error

type Options

type Options struct {
	// Domain serves apps as <app>.<space>.<domain>.
	Domain string
	// StateDir is where the provider keeps its records (a named volume
	// shared with the gateway, which reads the routes and keeps its
	// certificates there; default /var/lib/donkey).
	StateDir string
	// Registry is where builds are pushed (as the build engine reaches it).
	Registry config.Registry
	// AddonImages are direct repository overrides for managed services.
	AddonImages     config.InstallAddonImages
	CommonOfferings config.CommonOfferings
	// BusyboxImage runs file browsing and volume initialization helpers.
	BusyboxImage string
	// PullRegistry is the same registry as the Docker daemon reaches it
	// (e.g. 127.0.0.1:5000). Image references are rewritten from the push
	// host to this one before running. Empty means refs run as pushed.
	PullRegistry string
	// AIContainer is the openai addon's shared endpoint.
	AIContainer string
	// ProxyContainer is the shared endpoint for configured HTTP offerings.
	ProxyContainer string
	// TelemetryContainer accepts app-scoped OTLP metrics on every space
	// network.
	TelemetryContainer string
	// ServerContainer/OrchestratorContainer/GatewayContainer name donkey's
	// own containers, so the provider can attach them to every space network
	// (the server must reach apps for tunnels, the orchestrator to probe a
	// deploy's readiness, the gateway to proxy).
	ServerContainer       string
	OrchestratorContainer string
	GatewayContainer      string
	// TelemetryKey derives app-scoped ingestion tokens.
	TelemetryKey []byte
}

Options is what the Docker runtime needs to know about the installation.

type Route

type Route = config.GatewayRoute

Route has the same fields as Kubernetes route configuration. Docker stores it as a YAML record.

func ReadRoutes

func ReadRoutes(stateDir string) ([]Route, error)

ReadRoutes is the gateway's view: every route of every space, plus the system routes (the console's). It is exported for the gateway's file route source.

type Runtime

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

Runtime runs donkey's apps on a Docker engine.

func New

func New(opts Options) (*Runtime, error)

New connects to the Docker engine (socket or DOCKER_HOST) and returns the runtime.

func (*Runtime) AIProxyTokens

func (r *Runtime) AIProxyTokens(ctx context.Context) ([]string, error)

func (*Runtime) AppMeta

func (r *Runtime) AppMeta(ctx context.Context, space, app, key string) (string, error)

func (*Runtime) ApplyNetwork

func (r *Runtime) ApplyNetwork(ctx context.Context, cfg *config.AppConfig) (string, error)

ApplyNetwork changes how the app is reached — without a deploy: the route files are rewritten, the gateway picks them up within seconds. Existing shared-address routes keep serving; their exposure follows the app's.

func (*Runtime) AttachService

func (r *Runtime) AttachService(ctx context.Context, space, app, name string, binding map[string]string) (bool, error)

func (*Runtime) CheckSpaceFree

func (r *Runtime) CheckSpaceFree(ctx context.Context, space string) error

func (*Runtime) Checks

func (r *Runtime) Checks(ctx context.Context) []rt.Check

func (*Runtime) Client

func (r *Runtime) Client() *client.Client

Client exposes the underlying Docker client for Docker-specific callers (the installer).

func (*Runtime) CreateSpace

func (r *Runtime) CreateSpace(ctx context.Context, space string) error

func (*Runtime) DeleteSpace

func (r *Runtime) DeleteSpace(ctx context.Context, space string) error

func (*Runtime) Deploy

func (r *Runtime) Deploy(ctx context.Context, spec rt.DeploySpec, out rt.Progress) (deployErr error)

Deploy takes a built image live as a container. The same choreography as on Kubernetes — storage, declared services, the app, its routes — with Docker's vocabulary underneath.

func (*Runtime) Destroy

func (r *Runtime) Destroy(ctx context.Context, space, app string, keepData bool) error

func (*Runtime) DetachService

func (r *Runtime) DetachService(ctx context.Context, space, app, name string) error

DetachService drops the app's copy of a binding and every env reference to it — the stored ones, and donkey.yaml's in the run record as Kubernetes strips them from the Deployment — so the restart does not trip over them.

func (*Runtime) EnsureService

func (r *Runtime) EnsureService(ctx context.Context, space string, spec rt.ServiceSpec) (map[string]string, map[string]any, error)

func (*Runtime) EnsureSpaceConfigs

func (r *Runtime) EnsureSpaceConfigs(ctx context.Context) error

func (*Runtime) Evidence

func (r *Runtime) Evidence(ctx context.Context, space, app string) rt.Evidence

func (*Runtime) ExaProxyTokens

func (r *Runtime) ExaProxyTokens(ctx context.Context) ([]string, error)

func (*Runtime) GetEnv

func (r *Runtime) GetEnv(ctx context.Context, space, app string) (map[string]string, error)

func (*Runtime) HasData

func (r *Runtime) HasData(ctx context.Context, space, app string) bool

func (*Runtime) InitPlatformConfig

func (r *Runtime) InitPlatformConfig(ctx context.Context, initial config.PlatformConfig) (config.PlatformConfig, error)

func (*Runtime) InternalURL

func (r *Runtime) InternalURL(space, app string, port int) string

func (*Runtime) ListApps

func (r *Runtime) ListApps(ctx context.Context) ([]rt.AppRef, error)

func (*Runtime) ListFiles

func (r *Runtime) ListFiles(ctx context.Context, space, app, subPath string) ([]rt.FileEntry, error)

func (*Runtime) ListServices

func (r *Runtime) ListServices(ctx context.Context, space, owner string) ([]rt.ServiceBindingInfo, error)

func (*Runtime) ListSpaces

func (r *Runtime) ListSpaces(ctx context.Context) ([]string, error)

func (*Runtime) Logs

func (r *Runtime) Logs(ctx context.Context, space, app string, opts rt.LogOptions, out io.Writer) error

func (*Runtime) MakeDir

func (r *Runtime) MakeDir(ctx context.Context, space, app, subPath string) error

func (*Runtime) MoveFile

func (r *Runtime) MoveFile(ctx context.Context, space, app, from, to string) error

func (*Runtime) Network

func (r *Runtime) Network(ctx context.Context, space, app string) (*rt.NetworkState, error)

func (*Runtime) PlatformConfig

func (r *Runtime) PlatformConfig(context.Context) (config.PlatformConfig, error)

func (*Runtime) ReadFile

func (r *Runtime) ReadFile(ctx context.Context, space, app, subPath string, w io.Writer) error

func (*Runtime) ReconcileAppRoutes

func (r *Runtime) ReconcileAppRoutes(ctx context.Context, space, app string, protect bool) error

func (*Runtime) ReconcileOwnNetworks

func (r *Runtime) ReconcileOwnNetworks(ctx context.Context, every time.Duration)

ReconcileOwnNetworks keeps donkey's own containers attached to every space network for as long as ctx lives.

Attaching once is not enough, because more than one thing detaches them. Recreating a container drops all of its networks, and an install recreates both — but so does anyone who removes and re-runs one by hand. A deploy that lands while a container is briefly absent skips it silently: ensureSpace treats "no such container" as fine, since donkey may be running outside Docker in development. And a space network removed and recreated outside donkey comes back with nobody on it.

The gateway cannot repair this itself — it holds no Docker socket, only the state volume — so the server, which is the runtime provider, does it for both. The check costs one network list and a few no-op connects, and the failure it prevents is silent and total: every app in a space stops answering, with nothing in its own logs to say why.

func (*Runtime) ReconcileProxyNetworks

func (r *Runtime) ReconcileProxyNetworks(ctx context.Context)

The server publishes owned network ranges; the shared proxy reads this snapshot without a Docker socket. App IP reuse stays within the space's subnet, rather than inheriting a cached individual container identity.

func (*Runtime) RemoveFile

func (r *Runtime) RemoveFile(ctx context.Context, space, app, subPath string) error

func (*Runtime) RemoveService

func (r *Runtime) RemoveService(ctx context.Context, space, name string, keepData, force bool) ([]string, error)

func (*Runtime) Render

func (r *Runtime) Render(spec rt.DeploySpec) (string, error)

Render says what Deploy would do — there is no YAML to show on Docker, so it is the plan in words.

func (*Runtime) ResourceSamples

func (r *Runtime) ResourceSamples(ctx context.Context) ([]rt.ResourceSample, error)

ResourceSamples reads near-realtime Docker Engine stats for every running app container. Docker primes a non-streaming stats response with two CPU snapshots, which gives us cores used over that interval rather than a lifetime average. Calls are bounded so a large installation cannot fan out an unlimited number of socket requests.

func (*Runtime) Restart

func (r *Runtime) Restart(ctx context.Context, space, app string) (bool, error)

Restart recreates the app's container from its stored run record — that is what makes changed env and bindings take effect, exactly like a Kubernetes rollout re-reading its secrets.

func (*Runtime) ServiceAttachments

func (r *Runtime) ServiceAttachments(ctx context.Context, space, name string) ([]string, error)

func (*Runtime) ServiceBinding

func (r *Runtime) ServiceBinding(ctx context.Context, space, owner, name string) (map[string]string, error)

func (*Runtime) ServiceConnection

func (r *Runtime) ServiceConnection(ctx context.Context, space, name string) (rt.ServiceConnection, error)

func (*Runtime) ServiceEndpoint

func (r *Runtime) ServiceEndpoint(ctx context.Context, space, name string) (string, int32, error)

func (*Runtime) ServiceProxyAccess

func (r *Runtime) ServiceProxyAccess(ctx context.Context, sourceIP, offering string) (bool, error)

func (*Runtime) ServiceProxySpaceAccess

func (r *Runtime) ServiceProxySpaceAccess(ctx context.Context, space, offering string) (bool, error)

func (*Runtime) SetAppMeta

func (r *Runtime) SetAppMeta(ctx context.Context, space, app, key string, value *string) error

func (*Runtime) SetEnv

func (r *Runtime) SetEnv(ctx context.Context, space, app string, env map[string]string) error

func (*Runtime) SetPlatformConfig

func (r *Runtime) SetPlatformConfig(ctx context.Context, settings config.PlatformConfig) error

func (*Runtime) SetProxyServices

func (r *Runtime) SetProxyServices(services config.ProxyServices) error

SetProxyServices updates the shared proxy's read-only configuration file.

func (*Runtime) SetSpaceConfig

func (r *Runtime) SetSpaceConfig(ctx context.Context, space string, access config.SpaceConfig) error

func (*Runtime) SpaceConfig

func (r *Runtime) SpaceConfig(ctx context.Context, space string) (config.SpaceConfig, error)

func (*Runtime) Status

func (r *Runtime) Status(ctx context.Context, space, app string) (*rt.AppStatus, error)

func (*Runtime) StorageFolders

func (r *Runtime) StorageFolders(ctx context.Context, space, app string) ([]rt.StorageFolder, error)

func (*Runtime) UpdateSecurity

func (r *Runtime) UpdateSecurity(ctx context.Context, space, app, image, security string) error

func (*Runtime) ValidateSpace

func (r *Runtime) ValidateSpace(space string) error

func (*Runtime) WriteFile

func (r *Runtime) WriteFile(ctx context.Context, space, app, subPath string, in io.Reader) error

Jump to

Keyboard shortcuts

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