Documentation
¶
Overview ¶
Package provision is the app provisioning core (plan §7): a typed form spec (mooring.yaml under the hood) deterministically GENERATED into a safe compose. Mooring OWNS the compose — there is no raw-compose/Dockerfile paste path — so the dangerous compose keys (privileged, cap_add, host namespaces, host binds, :80/:443 publishes) SIMPLY DO NOT EXIST in its typed model (no input can produce them), and the generated YAML is still re-run through §5.6 as defense in depth.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Commit ¶
Commit writes files into a fresh 0700 staging dir under appsRoot, then promotes it to runDir via an atomic rename(2) — there is never a half-written app, and a crash leaves only a sweepable .staging-* dir (plan §7). appsRoot MUST be the parent of runDir on the SAME filesystem (rename(2) cannot cross filesystems). If runDir already exists it is atomically replaced (old moved aside, removed after the swap).
func Generate ¶
Generate validates the spec and renders a deterministic, safe compose document. The result is STILL meant to be run through §5.6 by the caller (defense in depth) — Generate guarantees safety by construction, §5.6 guarantees it again.
func SweepStaging ¶
func SweepStaging(appsRoot string)
SweepStaging removes stale staging / aside directories left by an interrupted commit (plan §7: a boot-time sweep clears stale staging). It never touches a committed app dir.
Types ¶
type Build ¶
Build marks a service whose image Mooring BUILDS from a generated Dockerfile. Context is the build context (run_dir-relative; "." = the app's checkout) and Dockerfile is the run_dir-relative path of the Mooring-generated Dockerfile. Both stay under the run dir — the §5.6 validator re-confines the context at deploy time.
type EnvVar ¶
type EnvVar struct {
Key string `json:"key"`
Value string `json:"value"`
Secret string `json:"secret"`
}
EnvVar is a generated service's env entry: a literal Value XOR a Secret reference. A secret renders as ${Secret} (resolved from the encrypted store's 0600 --env-file at deploy); a literal renders inline. Exactly one of Value/Secret.
type File ¶
File is one artifact to write into the app run dir at commit (compose, an optional Dockerfile). RelPath is run_dir-relative and confined.
type NofileLimit ¶ added in v0.4.2
type Port ¶
type Port struct {
Internal int `json:"internal"`
Publish bool `json:"publish"`
Public bool `json:"public"`
Protocol string `json:"protocol,omitempty"` // "" (=tcp) | "tcp" | "udp"
Published int `json:"published,omitempty"` // host port (default = internal)
}
Port is one published container port. Internal is the container port; Publish maps it to the host. Public binds 0.0.0.0 (requires an explicit ack) — the default binds loopback only (plan §7: 127.0.0.1 unless "expose publicly").
type Service ¶
type Service struct {
Name string `json:"name"`
Image string `json:"image"`
Build *Build `json:"build,omitempty"`
Ports []Port `json:"ports"`
Volumes []Volume `json:"volumes"`
Env []EnvVar `json:"env"` // per-service env: literal XOR secret ref
Command []string `json:"command"` // exec form (no shell)
Healthcheck []string `json:"healthcheck"` // exec form, e.g. ["curl","-f","http://localhost/health"]
Restart string `json:"restart"`
DependsOn []string `json:"depends_on"` // sibling service names
// MemLimit/MemReservation are compose byte-size strings ("768m", "1g"); empty omits the
// key. A limit bounds each replica (per-container OOM protection) and makes the scaler's
// mem trigger per-service. Validated in the definition layer; allow-listed in compose.
MemLimit string `json:"mem_limit,omitempty"`
MemReservation string `json:"mem_reservation,omitempty"`
// StopGracePeriod is a compose duration ("60s", "1m30s"); empty omits the key. Widens
// the SIGTERM→SIGKILL drain window on stop. Validated in the definition layer.
StopGracePeriod string `json:"stop_grace_period,omitempty"`
// Ulimits are per-container limits (currently only nofile). Validated in the
// definition layer; allow-listed in compose (§5.6). nil omits the compose key.
Ulimits *Ulimits `json:"ulimits,omitempty"`
// Scheduled marks a SCHEDULED-ONLY service (referenced by a scheduled_task): the generator
// gives it a compose profile so `up` never starts it; Mooring runs it on its interval via
// `compose run --rm`. Not a security-relevant field (no compose privilege), just placement.
Scheduled bool `json:"scheduled,omitempty"`
}
Service is one generated service. Only safe fields exist here by construction. A service is `Image` (pull) XOR `Build` (Mooring generates the Dockerfile).
type Ulimits ¶ added in v0.4.2
type Ulimits struct {
Nofile *NofileLimit `json:"nofile,omitempty"`
}
Ulimits / NofileLimit mirror the definition types for compose `ulimits.nofile`.
type Volume ¶
type Volume struct {
Name string `json:"name"` // named volume
Source string `json:"source"` // relative bind path, confined under run_dir
Target string `json:"target"` // absolute path inside the container
ReadOnly bool `json:"read_only"`
}
Volume is a named volume XOR a run_dir-confined bind. Exactly one of Name/Source.
Source Files