Documentation
¶
Overview ¶
Package docker is the Phase 1 Runtime implementation backed by a local Docker daemon via github.com/docker/docker/client.
Sandboxes are plain Docker containers. The sandbox ID is used verbatim as the container name, so lookups go directly through the Docker API without an auxiliary bookkeeping layer. A label (edvabe.sandbox.id=<id>) is also stamped on every container so a future reconnect flow can enumerate orphans on edvabe restart.
Index ¶
- Constants
- func DiscoverHost() (string, error)
- type Runtime
- func (r *Runtime) AgentEndpoint(sandboxID string) (host string, port int, err error)
- func (r *Runtime) BuildImage(ctx context.Context, req runtime.BuildRequest) error
- func (r *Runtime) Close() error
- func (r *Runtime) Commit(ctx context.Context, sandboxID, imageTag string) error
- func (r *Runtime) Create(ctx context.Context, req runtime.CreateRequest) (*runtime.SandboxHandle, error)
- func (r *Runtime) Destroy(ctx context.Context, sandboxID string) error
- func (r *Runtime) Host() string
- func (r *Runtime) ListManaged(ctx context.Context) ([]runtime.ManagedContainer, error)
- func (r *Runtime) Name() string
- func (r *Runtime) Network() string
- func (r *Runtime) OwnIPv4() string
- func (r *Runtime) Pause(ctx context.Context, sandboxID string) error
- func (r *Runtime) Start(ctx context.Context, sandboxID string) error
- func (r *Runtime) Stats(ctx context.Context, sandboxID string) (*runtime.Stats, error)
- func (r *Runtime) Stop(ctx context.Context, sandboxID string) error
- func (r *Runtime) Unpause(ctx context.Context, sandboxID string) error
Constants ¶
const ( // LabelSandboxID stamps the sandbox ID on every container edvabe // creates. Used by doctor / future reconnect to enumerate managed // containers. LabelSandboxID = "edvabe.sandbox.id" // LabelManaged is a truthy marker so operators can filter edvabe's // containers apart from hand-launched ones. LabelManaged = "edvabe.managed" )
Variables ¶
This section is empty.
Functions ¶
func DiscoverHost ¶
DiscoverHost returns the Docker host URI to connect to, honoring DOCKER_HOST and otherwise probing the well-known socket paths in the order below. The first path that stats returns the URI `unix://<path>`.
- $DOCKER_HOST (unchanged — may be tcp://, ssh://, unix://)
- /var/run/docker.sock — Docker Desktop / upstream
- ~/.colima/docker.sock — Colima default profile
- ~/.orbstack/run/docker.sock — OrbStack
- ~/.local/share/containers/podman/machine/podman.sock — Podman
Types ¶
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime implements runtime.Runtime against a local Docker daemon.
The zero value is not usable — construct with New.
func New ¶
New constructs a Docker-backed Runtime, discovering the daemon socket via DOCKER_HOST or a list of well-known paths (Docker Desktop, Colima, OrbStack, Podman). Negotiates the Docker API version on first call so the client works across daemon versions.
The Docker network sandbox containers are attached to is resolved in this order:
- EDVABE_DOCKER_NETWORK env var (or --docker-network flag) — explicit
- Auto-detected from edvabe's own container's networks when edvabe runs inside Docker / Compose — zero-config for the common case
- Default Docker `bridge` network
(2) makes Docker Compose deployments work without the user having to look up and configure the compose network name.
func (*Runtime) AgentEndpoint ¶
AgentEndpoint returns the host:port the reverse proxy should forward envd traffic to for a given sandbox. First consults the in-memory cache (populated by Create), then falls back to a live ContainerInspect so the call still works if edvabe restarts mid-sandbox.
func (*Runtime) BuildImage ¶
BuildImage builds an image from a filesystem build context. Used by the upstream AgentProvider and by the template builder. Consumes the full build output stream before returning so the image is ready when BuildImage returns. If req.LogWriter is non-nil, each line of docker daemon output is forwarded to it as the build progresses.
func (*Runtime) Commit ¶
Commit snapshots a sandbox container's filesystem as a new image tagged imageTag. Uses `docker commit` — so the resulting image captures writable-layer mutations (installed packages, created files) but NOT running process memory. Callers should pause the container first if they need a consistent snapshot.
func (*Runtime) Create ¶
func (r *Runtime) Create(ctx context.Context, req runtime.CreateRequest) (*runtime.SandboxHandle, error)
Create creates + starts a container from req.Image, names it after req.SandboxID, and resolves its bridge IP for the reverse proxy. On any error after ContainerCreate, the partial container is force-removed so the caller doesn't have to clean up.
func (*Runtime) Destroy ¶
Destroy stops and removes the container named after sandboxID. The Force flag terminates the process without waiting for a graceful shutdown; Phase 1 prioritizes teardown speed over clean exits.
func (*Runtime) Host ¶
Host reports the Docker host URI the runtime resolved to (useful for logging and doctor output).
func (*Runtime) ListManaged ¶ added in v0.2.0
ListManaged enumerates containers labeled edvabe.managed=true (including paused and stopped) and returns a normalized view. Individual inspect failures are swallowed — the caller is rehydrating on startup, one bad container shouldn't abort the whole sweep. Containers in transitional states (dead / removing / created but never started) are filtered out so the manager only sees entries it can act on.
func (*Runtime) Network ¶
Network reports the Docker network name sandbox containers are attached to ("" means default bridge).
func (*Runtime) OwnIPv4 ¶
OwnIPv4 returns edvabe's own IPv4 address on the sandbox network, or "" when it can't be determined (not containerized, inspection failed, etc.). Used to default --dns-answer.
func (*Runtime) Pause ¶
Pause freezes the container's processes via `docker pause`. The container stays resident in memory and keeps its network namespace; Unpause thaws it again. This is NOT a memory snapshot — rebooting the host drops the state. Callers surface that caveat to users.
func (*Runtime) Start ¶
Start boots a previously stopped container and refreshes the cached agent endpoint. Docker may assign a new bridge IP after restart, so we re-inspect and overwrite the entry the reverse proxy consults.
func (*Runtime) Stats ¶
Stats returns resource usage for a running sandbox. Asks the daemon to include a prior sample so CPU percentages can be computed from the delta without the caller having to stream and diff samples themselves.
Source Files