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
- func AttachOwnContainers(ctx context.Context, cli *client.Client, names ...string) error
- func IdentityLabelKeys() []string
- func MatchesSystemLabels(actual map[string]string, role string) bool
- func ReadGatewayPolicies(dir string) (map[string]config.SpaceConfig, config.PlatformConfig, error)
- func ReadRecordFile(path string) ([]byte, error)
- func SystemLabels(role string) map[string]string
- func SystemRoleOf(containerName string) string
- func WriteSystemRoute(stateDir, name string, r Route) error
- type GatewayAdapter
- func (g *GatewayAdapter) GatewayCA(ctx context.Context, create func() ([]byte, []byte, error)) ([]byte, []byte, error)
- func (g *GatewayAdapter) GatewayCertificateCache() autocert.Cache
- func (g *GatewayAdapter) GatewaySnapshot(ctx context.Context) (rt.GatewaySnapshot, error)
- func (g *GatewayAdapter) PrepareGateway(context.Context) error
- type Options
- type Route
- type Runtime
- func (r *Runtime) AIProxyTokens(ctx context.Context) ([]string, error)
- func (r *Runtime) AppMeta(ctx context.Context, space, app, key string) (string, error)
- func (r *Runtime) ApplyNetwork(ctx context.Context, cfg *config.AppConfig) (string, error)
- func (r *Runtime) AttachService(ctx context.Context, space, app, name string, binding map[string]string) (bool, error)
- func (r *Runtime) CheckSpaceFree(ctx context.Context, space string) error
- func (r *Runtime) Checks(ctx context.Context) []rt.Check
- func (r *Runtime) Client() *client.Client
- func (r *Runtime) CreateSpace(ctx context.Context, space string) error
- func (r *Runtime) DeleteSpace(ctx context.Context, space string) error
- func (r *Runtime) Deploy(ctx context.Context, spec rt.DeploySpec, out rt.Progress) (deployErr error)
- func (r *Runtime) Destroy(ctx context.Context, space, app string, keepData bool) error
- func (r *Runtime) DetachService(ctx context.Context, space, app, name string) error
- func (r *Runtime) EnsureService(ctx context.Context, space string, spec rt.ServiceSpec) (map[string]string, map[string]any, error)
- func (r *Runtime) EnsureSpaceConfigs(ctx context.Context) error
- func (r *Runtime) Evidence(ctx context.Context, space, app string) rt.Evidence
- func (r *Runtime) ExaProxyTokens(ctx context.Context) ([]string, error)
- func (r *Runtime) GetEnv(ctx context.Context, space, app string) (map[string]string, error)
- func (r *Runtime) HasData(ctx context.Context, space, app string) bool
- func (r *Runtime) InitPlatformConfig(ctx context.Context, initial config.PlatformConfig) (config.PlatformConfig, error)
- func (r *Runtime) InternalURL(space, app string, port int) string
- func (r *Runtime) ListApps(ctx context.Context) ([]rt.AppRef, error)
- func (r *Runtime) ListFiles(ctx context.Context, space, app, subPath string) ([]rt.FileEntry, error)
- func (r *Runtime) ListServices(ctx context.Context, space, owner string) ([]rt.ServiceBindingInfo, error)
- func (r *Runtime) ListSpaces(ctx context.Context) ([]string, error)
- func (r *Runtime) Logs(ctx context.Context, space, app string, opts rt.LogOptions, out io.Writer) error
- func (r *Runtime) MakeDir(ctx context.Context, space, app, subPath string) error
- func (r *Runtime) MoveFile(ctx context.Context, space, app, from, to string) error
- func (r *Runtime) Network(ctx context.Context, space, app string) (*rt.NetworkState, error)
- func (r *Runtime) PlatformConfig(context.Context) (config.PlatformConfig, error)
- func (r *Runtime) ReadFile(ctx context.Context, space, app, subPath string, w io.Writer) error
- func (r *Runtime) ReconcileAppRoutes(ctx context.Context, space, app string, protect bool) error
- func (r *Runtime) ReconcileOwnNetworks(ctx context.Context, every time.Duration)
- func (r *Runtime) ReconcileProxyNetworks(ctx context.Context)
- func (r *Runtime) RemoveFile(ctx context.Context, space, app, subPath string) error
- func (r *Runtime) RemoveService(ctx context.Context, space, name string, keepData, force bool) ([]string, error)
- func (r *Runtime) Render(spec rt.DeploySpec) (string, error)
- func (r *Runtime) ResourceSamples(ctx context.Context) ([]rt.ResourceSample, error)
- func (r *Runtime) Restart(ctx context.Context, space, app string) (bool, error)
- func (r *Runtime) ServiceAttachments(ctx context.Context, space, name string) ([]string, error)
- func (r *Runtime) ServiceBinding(ctx context.Context, space, owner, name string) (map[string]string, error)
- func (r *Runtime) ServiceConnection(ctx context.Context, space, name string) (rt.ServiceConnection, error)
- func (r *Runtime) ServiceEndpoint(ctx context.Context, space, name string) (string, int32, error)
- func (r *Runtime) ServiceProxyAccess(ctx context.Context, sourceIP, offering string) (bool, error)
- func (r *Runtime) ServiceProxySpaceAccess(ctx context.Context, space, offering string) (bool, error)
- func (r *Runtime) SetAppMeta(ctx context.Context, space, app, key string, value *string) error
- func (r *Runtime) SetEnv(ctx context.Context, space, app string, env map[string]string) error
- func (r *Runtime) SetPlatformConfig(ctx context.Context, settings config.PlatformConfig) error
- func (r *Runtime) SetProxyServices(services config.ProxyServices) error
- func (r *Runtime) SetSpaceConfig(ctx context.Context, space string, access config.SpaceConfig) error
- func (r *Runtime) SpaceConfig(ctx context.Context, space string) (config.SpaceConfig, error)
- func (r *Runtime) Status(ctx context.Context, space, app string) (*rt.AppStatus, error)
- func (r *Runtime) StorageFolders(ctx context.Context, space, app string) ([]rt.StorageFolder, error)
- func (r *Runtime) UpdateSecurity(ctx context.Context, space, app, image, security string) error
- func (r *Runtime) ValidateSpace(space string) error
- func (r *Runtime) WriteFile(ctx context.Context, space, app, subPath string, in io.Reader) error
Constants ¶
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 ¶
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 ¶
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 ¶
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 ¶
SystemLabels is the ownership/role vocabulary shared by the direct Docker installer, generated Compose bundles, and runtime-created resources.
func SystemRoleOf ¶
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 ¶
WriteSystemRoute records a route donkey's installer owns (the console).
Types ¶
type GatewayAdapter ¶
type GatewayAdapter struct{ StateDir string }
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 ¶
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 (*Runtime) AIProxyTokens ¶
func (*Runtime) ApplyNetwork ¶
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 (*Runtime) CheckSpaceFree ¶
func (*Runtime) Client ¶
Client exposes the underlying Docker client for Docker-specific callers (the installer).
func (*Runtime) CreateSpace ¶
func (*Runtime) DeleteSpace ¶
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) DetachService ¶
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 (*Runtime) EnsureSpaceConfigs ¶
func (*Runtime) ExaProxyTokens ¶
func (*Runtime) InitPlatformConfig ¶
func (r *Runtime) InitPlatformConfig(ctx context.Context, initial config.PlatformConfig) (config.PlatformConfig, error)
func (*Runtime) ListServices ¶
func (*Runtime) PlatformConfig ¶
func (*Runtime) ReconcileAppRoutes ¶
func (*Runtime) ReconcileOwnNetworks ¶
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 ¶
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 (*Runtime) RemoveService ¶
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 ¶
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 ¶
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 (*Runtime) ServiceBinding ¶
func (*Runtime) ServiceConnection ¶
func (*Runtime) ServiceEndpoint ¶
func (*Runtime) ServiceProxyAccess ¶
func (*Runtime) ServiceProxySpaceAccess ¶
func (*Runtime) SetAppMeta ¶
func (*Runtime) SetPlatformConfig ¶
func (*Runtime) SetProxyServices ¶
func (r *Runtime) SetProxyServices(services config.ProxyServices) error
SetProxyServices updates the shared proxy's read-only configuration file.