Documentation
¶
Overview ¶
Package platformstack installs and updates Miabi's own stack directly against the Docker API, with every component tagged io.miabi.managed-by=miabi. Compose owns what Compose created, so Miabi could never truly self-update while Compose held the lifecycle. It runs from the CLI, outside the container.
Index ¶
- Constants
- Variables
- func GomaConfig() []byte
- func ManifestPath() string
- func PortConflictError(conflicts []PortConflict) error
- func Save(path string, m *Manifest) error
- type Component
- type Gateway
- type Images
- type Manifest
- type NetworkConfig
- type PortConflict
- type Registry
- type Secrets
- type Service
- func (s *Service) CheckOrphanedData(ctx context.Context) error
- func (s *Service) CheckPorts(ctx context.Context) ([]PortConflict, error)
- func (s *Service) Component(m *Manifest, name string) (component, bool)
- func (s *Service) ComponentNames(m *Manifest) []string
- func (s *Service) Converge(ctx context.Context, m *Manifest) error
- func (s *Service) ConvergeData(ctx context.Context, m *Manifest) error
- func (s *Service) Discover(ctx context.Context) ([]Component, error)
- func (s *Service) EnsureGatewayConfig(ctx context.Context, m *Manifest) error
- func (s *Service) Restart(ctx context.Context, m *Manifest, only string) error
- func (s *Service) Rollout(ctx context.Context, m *Manifest, name, newImage string, ...) error
- func (s *Service) Teardown(ctx context.Context, withVolumes bool) error
- func (s *Service) ValidateGatewayConfig(ctx context.Context, m *Manifest) error
Constants ¶
const ( // DefaultGeoIPFile is the GeoIP database's name beside goma.yml — what the docs // tell operators to call the file they supply. Provider-neutral, because Miabi // does not choose the provider. DefaultGeoIPFile = "country.mmdb" // LegacyGeoIPFile is accepted too. It is MaxMind's own download name, so an // operator following MaxMind's instructions lands on it without thinking — and // earlier Miabi releases downloaded the file under that name. LegacyGeoIPFile = "GeoLite2-Country.mmdb" )
const ( ConfigPathEnv = "MIABI_CONFIG_FILE" ManifestPathEnv = "MIABI_STACK_FILE" )
ConfigPathEnv overrides the resolved path (tests, rootless installs, a second stack on one host). ManifestPathEnv is the older spelling and is still honoured.
const ( ContainerControlPlane = "miabi" ContainerPostgres = "miabi-postgres" ContainerRedis = "miabi-redis" ContainerGateway = "miabi-gateway" )
Container names. They match examples/compose/compose.yaml deliberately: an operator's muscle memory (`docker logs miabi`) keeps working across both install paths, and Phase 1's name shield already knows them.
const ( VolumePGData = "mb-platform-pgdata" VolumeRedisData = "mb-platform-redisdata" VolumeLogs = "mb-platform-logs" VolumeGatewayCerts = "mb-platform-gateway-certs" VolumeGatewayProviders = "mb-platform-gateway-providers" // VolumeGatewayConfig is NO LONGER CREATED: the gateway config is a bind-mounted // file on the host, not a copy in a volume. It survives here only so Teardown can // clean it up on installs that predate the change. VolumeGatewayConfig = "mb-platform-gateway-config" )
Volumes. The mb- prefix marks them as Miabi's own, which dockerimport's name shield already recognizes, so they are never offered for import.
const ( DefaultPostgresImage = "postgres:17-alpine" DefaultRedisImage = "redis:7-alpine" DefaultGatewayImage = "jkaninda/goma-gateway:0.14.0" // DefaultRunnerImage floats on :latest, unlike every other default here. The runner is the one image // the stack does not RUN — it only names what a CI runner should be enrolled with — so it carries none // of the reproducibility weight, and install.sh passes the version this release was tested against. DefaultRunnerImage = "miabi/runner:latest" DefaultNetwork = "miabi" DefaultSubnet = "10.63.0.0/16" // DefaultInternalNetwork carries the platform's own traffic. It is separate from DefaultNetwork // because that one is the shared proxy fabric: every routed app joins it, so anything reachable // there is reachable from a tenant container — and Postgres holds one superuser password for the // whole control plane. DefaultInternalNetwork = "miabi-internal" // DefaultInternalSubnet sits BELOW DefaultSubnet, not above: 10.64.0.0/12 is the workspace // allocator's pool (MIABI_NETWORK_POOL_CIDR), so 10.64.0.0/16 would collide with the first // workspace block Miabi hands out. DefaultInternalSubnet = "10.62.0.0/16" )
Default images. Overridable in the manifest; pinned here so a bare `miabi setup` is reproducible rather than tracking whatever :latest happens to be. NOTE the tags carry no leading "v": git tags do (v0.11.0), Docker tags do not — the git form produced an image reference that does not exist.
const ( // DefaultGomaLogLevel matches Goma's own default; writing it down makes the knob // visible. Real effect, measured: info emits 28 lines and 0 DEBUG on boot, debug // emits 51 lines and 22 DEBUG. DefaultGomaLogLevel = "info" // DefaultGomaAnalytics turns on the per-request event stream Goma publishes to Redis. On, because the // consumer runs by default and otherwise every analytics dashboard sits empty. Seeded into gateway.env // rather than the spec, since a spec variable becomes reserved and would refuse any operator value. DefaultGomaAnalytics = "true" )
Seeded gateway.env defaults, written into the manifest so they are discoverable rather than folklore.
const ( DefaultTimezone = "UTC" // DefaultLogLevel matches what the control plane would pick anyway in production; // writing it down makes it discoverable instead of folklore. DefaultLogLevel = "info" )
Seeded env defaults, written into the manifest rather than applied invisibly, so `env:` shows an operator the two knobs they are most likely to want and where to change them. Both stay ordinary editable entries — neither needs to agree with anything else in the manifest.
const CurrentVersion = 1
CurrentVersion is the manifest schema version this build writes.
const DefaultConfigPath = "/etc/miabi/miabi.yaml"
DefaultConfigPath is where the installed stack's desired state lives. It has to be a file on the host, not the database: Postgres is itself a component, so the CLI cannot read the database to learn how to start the database. Miabi *writes* it, so it can never disagree with what Miabi actually did.
const DefaultGatewayConfigFile = "goma.yml"
DefaultGatewayConfigFile is the gateway config's name beside miabi.yaml.
const LegacyConfigPath = "/etc/miabi/stack.yaml"
LegacyConfigPath is the pre-rename location. It is no longer read implicitly — but it is still *detected*, so an install that predates the rename gets told to run `miabi stack migrate-config` instead of "not installed". It is never deleted on the operator's behalf: it holds the database password, and backup scripts may point at it.
Variables ¶
var ErrLegacyConfig = errors.New("the stack manifest is at its pre-1.8 path")
ErrLegacyConfig means the manifest is at the pre-rename LegacyConfigPath. It is deliberately NOT an ErrNotInstalled: this host *is* installed, and telling its operator otherwise sends them looking for a Compose stack that was never there.
var ErrNotInstalled = errors.New("no Miabi stack manifest found")
ErrNotInstalled means there is no stack manifest — nothing was installed by the CLI here. It does NOT mean there is no Miabi: a Compose install has no manifest either, and callers say so.
var ErrOrphanedData = errors.New("an existing Miabi database was found, but its manifest is missing")
ErrOrphanedData means Postgres data is already on this host, but the manifest that holds its password is gone.
Functions ¶
func GomaConfig ¶
func GomaConfig() []byte
GomaConfig exposes the embedded config so the drift test can compare it.
func ManifestPath ¶
func ManifestPath() string
ManifestPath resolves the manifest location: MIABI_CONFIG_FILE, else the older MIABI_STACK_FILE, else /etc/miabi/miabi.yaml. The legacy /etc/miabi/stack.yaml is no longer read implicitly — Load detects it and says how to migrate, which beats silently operating on a path the operator was told is gone.
func PortConflictError ¶
func PortConflictError(conflicts []PortConflict) error
PortConflictError renders conflicts as something an operator can act on.
Types ¶
type Component ¶
type Component struct {
Name string
Role string
State string // running, exited, …
Health string // healthy, unhealthy, starting, "" (no healthcheck)
Image string
ManagedBy string // compose | miabi | external | "" (an install predating labels)
Status string
}
Component is a running piece of the platform stack, as found on the engine.
type Gateway ¶
type Gateway struct {
// Config is the gateway config file, relative to the manifest's own directory
// (so it sits next to miabi.yaml and is backed up with it). Absolute paths are
// taken as-is. Empty means goma.yml.
Config string `yaml:"config,omitempty"`
// ConfigSHA is the digest of the DEFAULT config Miabi last wrote to that file. It is what lets an
// unmodified config keep receiving upstream improvements while a customized one is never clobbered.
// Without it, either customization is impossible or every install is frozen on its shipped config.
ConfigSHA string `yaml:"config_sha,omitempty"`
// Env is the gateway container's environment: anything the config interpolates, plus
// GOMA_CONFIG_ENCRYPTION_KEY. Variables Miabi sets itself are refused here, exactly as in the top-level
// env — a manifest where `domain` and `gateway.env.MIABI_DOMAIN` disagree has two sources of truth.
Env map[string]string `yaml:"env,omitempty"`
}
Gateway configures Goma: its config file and its environment. The config is a FILE ON THE HOST, bind-mounted read-only, not copied into a volume — copying makes the volume the source of truth and the host file a stale duplicate every converge silently overwrites.
type Images ¶
type Images struct {
Miabi string `yaml:"miabi"`
Postgres string `yaml:"postgres"`
Redis string `yaml:"redis"`
Gateway string `yaml:"gateway"`
// Runner is not run by the stack; it is the image shown in the runner enrollment command, so it belongs
// to the install's identity even though nothing here starts it. It is therefore the one image whose
// default floats on :latest — see DefaultRunnerImage. install.sh still pins it to the tested version.
Runner string `yaml:"runner"`
}
Images pins every image the stack runs. Each is a full ref (repo:tag), not a bare tag: the point of pinning is that `miabi setup` on two hosts a month apart produces the same stack.
type Manifest ¶
type Manifest struct {
// Version is the manifest schema, not the Miabi version.
Version int `yaml:"version"`
Domain string `yaml:"domain"`
WebURL string `yaml:"web_url"`
ACMEEmail string `yaml:"acme_email"`
// ControlURL is the URL remote nodes and agents reach this control plane at. It defaults to WebURL,
// which is right for a single public hostname, but is separate because a node on a private network may
// reach the control plane at an address the public panel URL never resolves to.
ControlURL string `yaml:"control_url"`
Network NetworkConfig `yaml:"network"`
// InternalNetwork is the PRIVATE network the platform's own components talk over — the control
// plane to Postgres and Redis, the gateway to both of those. Network above stays what it always
// was: the shared proxy fabric routed apps join, which is why nothing platform-internal may sit
// on it. Added after the fact, so it is a sibling key rather than a nested one: every manifest
// written before this release keeps parsing and gains the network on its next converge.
InternalNetwork NetworkConfig `yaml:"internal_network"`
Images Images `yaml:"images"`
Secrets Secrets `yaml:"secrets"`
Registry Registry `yaml:"registry"`
Gateway Gateway `yaml:"gateway"`
// Env are extra environment variables for the control plane — anything Miabi reads that this manifest
// does not already model. It may not contain a variable Miabi sets itself: two sources of truth for the
// database password means whichever loses is a silent misconfiguration. Normalize enforces this.
Env map[string]string `yaml:"env,omitempty"`
// DockerGID is the host's docker group, added to the control plane so it can read
// /var/run/docker.sock without running as root.
DockerGID string `yaml:"docker_gid,omitempty"`
// HostProc binds the host's /proc read-only into the control plane, so the Nodes page can report real
// host CPU and memory. A POINTER, because absent must mean "on" and a bool's zero value is false.
// Turning it off is safe — Miabi falls back to its own /proc, which already reflects host CPU/memory.
HostProc *bool `yaml:"host_proc"`
// contains filtered or unexported fields
}
Manifest is the installed stack's desired state.
func Defaults ¶
Defaults returns a manifest with everything the caller did not supply. miabiImage is the control-plane image, which has no sensible default — it is the version being installed, and the CLI knows it (it is that version).
func Load ¶
Load reads the manifest. A missing file returns ErrNotInstalled, which callers distinguish from a corrupt one — "you have not installed yet" and "your install is unreadable" need very different messages.
func (*Manifest) GenerateSecrets ¶
GenerateSecrets fills any secret that is still empty, leaving existing values alone so a re-install never rotates a live install's credentials out from under it (which would lock Miabi out of its own database).
type NetworkConfig ¶
type PortConflict ¶
type PortConflict struct {
Port int
// Holder names what has it — a container, or the host itself when the port is
// taken by a process Docker knows nothing about (a system nginx, Apache, or a
// Caddy installed from a package).
Holder string
// Container is true when Holder is a container name, which the operator can
// simply stop.
Container bool
}
PortConflict is something already holding a port the gateway needs.
func (PortConflict) String ¶
func (c PortConflict) String() string
type Registry ¶
type Registry struct {
Enabled bool `yaml:"enabled"`
// Host is the registry's own public hostname (registry.example.com). It gets a
// DNS record and its own TLS certificate, separate from the panel's.
Host string `yaml:"host,omitempty"`
}
Registry configures the built-in OCI registry. This manifest is the ONLY place enablement and the hostname live: the host anchors every stored image reference and decides which workspace owns an image, so the admin UI shows them read-only. The keys are written only when Enabled.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service installs and updates the stack.
func (*Service) CheckOrphanedData ¶
CheckOrphanedData refuses a FRESH install onto an existing Postgres volume. Postgres only honours POSTGRES_PASSWORD when it initializes an EMPTY data directory, so a freshly generated password can never authenticate. pg_isready does not check credentials, so nothing else catches it.
func (*Service) CheckPorts ¶
func (s *Service) CheckPorts(ctx context.Context) ([]PortConflict, error)
CheckPorts reports what would stop the gateway from binding 80 and 443, BEFORE anything is created. Two passes: Docker's own containers, which lets the message name the culprit; and an actual bind, for anything Docker cannot see — a system nginx is invisible to `docker ps` and to our netns.
func (*Service) Component ¶
Component returns the named component, or false. Exported so the CLI can validate `miabi upgrade <component>` before touching anything.
func (*Service) ComponentNames ¶
ComponentNames lists the updatable components, in dependency order.
func (*Service) Converge ¶
Converge brings the stack to the manifest's desired state in dependency order, and is safe to re-run: a component whose spec already matches is left alone. Postgres and Redis must be *healthy* before the control plane boots; the gateway goes last, so an incomplete stack fails closed.
func (*Service) ConvergeData ¶
ConvergeData brings up only the stateful components the control plane depends on and stops there. It exists for disaster recovery: a restore must load a dump into an EMPTY database, and a control plane booting first would AutoMigrate and collide with the dump's own CREATE TABLE statements.
func (*Service) Discover ¶
Discover lists the platform stack as it actually is — by role, so it answers for a Compose install just as well as a CLI one. That is the point: `miabi stack status` should describe whatever is running, not only what the CLI put there.
func (*Service) EnsureGatewayConfig ¶
EnsureGatewayConfig makes sure the gateway config exists, is valid, and is honest about who owns it: absent writes the shipped default and records its digest; a file still matching that digest may be replaced by a newer default; a file that differs was edited by the operator and is never touched.
func (*Service) Restart ¶
Restart restarts the stack, or one component. It restarts CONTAINERS rather than recreating them, so it re-reads what is on disk (Goma watches its providers directory but NOT its base config); anything changing a spec needs `miabi setup`. Order matters: stores first, gateway last.
func (*Service) Rollout ¶
func (s *Service) Rollout(ctx context.Context, m *Manifest, name, newImage string, onPhase func(string, error)) error
Rollout replaces one component with a new image and returns the manifest field to persist. It is the update path; Converge is the install path.
func (*Service) Teardown ¶
Teardown removes the stack's containers. Volumes are kept unless withVolumes: the database lives in one, and `uninstall` is far too easy to type for it to be the thing that silently destroys it. Reverse dependency order — gateway, control plane, then the stores it depends on.
func (*Service) ValidateGatewayConfig ¶
ValidateGatewayConfig checks the gateway config without writing it. EnsureGatewayConfig would also (re)write the file; a restart must not — the whole reason to restart is that the operator changed something on disk, and rewriting it underneath them would be the opposite of what they asked for.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package docker is the Docker seam the platform-stack engine talks through.
|
Package docker is the Docker seam the platform-stack engine talks through. |
|
Package saferollout replaces a running container with a new image without a blind cutover.
|
Package saferollout replaces a running container with a new image without a blind cutover. |
|
Package selfcontainer detects the Docker container ID of the running process, so Miabi can recognise its own container and refuse to stop or delete it from the admin containers list — which would take the platform offline.
|
Package selfcontainer detects the Docker container ID of the running process, so Miabi can recognise its own container and refuse to stop or delete it from the admin containers list — which would take the platform offline. |
|
Package stackcmd is the behaviour behind the host-side verbs — install/converge, upgrade, restart, status and uninstall — with no command-line framework attached.
|
Package stackcmd is the behaviour behind the host-side verbs — install/converge, upgrade, restart, status and uninstall — with no command-line framework attached. |