stack

package
v1.8.3 Latest Latest
Warning

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

Go to latest
Published: Aug 17, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

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

View Source
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"
)
View Source
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.

View Source
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.

View Source
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.

View Source
const (
	DefaultPostgresImage = "postgres:17-alpine"
	DefaultRedisImage    = "redis:7-alpine"
	DefaultGatewayImage  = "jkaninda/goma-gateway:latest"
	// 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"
)

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.

View Source
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.

View Source
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.

View Source
const CurrentVersion = 1

CurrentVersion is the manifest schema version this build writes.

View Source
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.

View Source
const DefaultGatewayConfigFile = "goma.yml"

DefaultGatewayConfigFile is the gateway config's name beside miabi.yaml.

View Source
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

View Source
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.

View Source
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.

View Source
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.

func Save

func Save(path string, m *Manifest) error

Save writes the manifest atomically at 0600, creating its directory. Atomic because this file is the only record of the install's secrets: a partial write from a killed process would lose the database password, and with it the database.

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"`
	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

func Defaults(miabiImage string) *Manifest

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

func Load(path string) (*Manifest, error)

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

func (m *Manifest) GenerateSecrets() error

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).

func (*Manifest) ImageFor

func (m *Manifest) ImageFor(container string) (string, bool)

ImageFor is the read-only form of ImagePin, for drift reporting.

func (*Manifest) ImagePin

func (m *Manifest) ImagePin(container string) (*string, bool)

ImagePin returns a pointer to the manifest field pinning the named component's image, so an update can write the new value back to the right place. ok is false for a name that is not a stack component.

func (*Manifest) Normalize

func (m *Manifest) Normalize() error

Normalize fills in derived fields and validates what the caller must supply. It is called by Install and Update, so a hand-edited manifest gets the same treatment as a generated one.

type NetworkConfig

type NetworkConfig struct {
	Name   string `yaml:"name"`
	Subnet string `yaml:"subnet"`
}

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 Secrets

type Secrets struct {
	DBPassword    string `yaml:"db_password"`
	RedisPassword string `yaml:"redis_password"`
	JWTSecret     string `yaml:"jwt_secret"`
	EncryptionKey string `yaml:"encryption_key"`
	AdminEmail    string `yaml:"admin_email"`
	AdminPassword string `yaml:"admin_password"`
}

type Service

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

Service installs and updates the stack.

func New

func New(dc docker.Client, log func(string, ...any), manifestPath string) *Service

func (*Service) CheckOrphanedData

func (s *Service) CheckOrphanedData(ctx context.Context) error

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

func (s *Service) Component(m *Manifest, name string) (component, bool)

Component returns the named component, or false. Exported so the CLI can validate `miabi upgrade <component>` before touching anything.

func (*Service) ComponentNames

func (s *Service) ComponentNames(m *Manifest) []string

ComponentNames lists the updatable components, in dependency order.

func (*Service) Converge

func (s *Service) Converge(ctx context.Context, m *Manifest) error

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

func (s *Service) ConvergeData(ctx context.Context, m *Manifest) error

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

func (s *Service) Discover(ctx context.Context) ([]Component, error)

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

func (s *Service) EnsureGatewayConfig(ctx context.Context, m *Manifest) error

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

func (s *Service) Restart(ctx context.Context, m *Manifest, only string) error

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

func (s *Service) Teardown(ctx context.Context, withVolumes bool) error

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

func (s *Service) ValidateGatewayConfig(ctx context.Context, m *Manifest) error

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.

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.

Jump to

Keyboard shortcuts

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