stack

package
v1.10.15 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: AGPL-3.0, Apache-2.0 Imports: 29 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:1.0.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-proxy"
	// LegacyNetwork is the proxy network's name before it became DefaultNetwork. Installs created
	// before the rename keep it: their app containers are attached to it by name.
	LegacyNetwork = "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.

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 APIVersion = "install.miabi.io/v1"

APIVersion is the only apiVersion an install document may carry. It is deliberately not the miabi.io/v1 of workspace resources: that schema publishes its kinds as a generated enum, so a ControlPlane inside it would read as something the apply API accepts, which it never will.

View Source
const BackupSuffix = ".bak"

BackupSuffix names the copy ConvertFile leaves behind.

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 KindControlPlane = "ControlPlane"

KindControlPlane is the install document's only kind today.

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.

View Source
const SchemaFileName = "install.miabi.io-v1.schema.json"

SchemaFileName is the published file name, kept here so the generator, the docs site and the editor extension cannot disagree about it.

View Source
const SchemaID = "https://docs.miabi.io/schema/install.miabi.io-v1.schema.json"

SchemaID is where the generated schema is published. Editors resolve $ref against it, so it has to be the URL the file is actually served from.

View Source
const UserConfigDir = ".miabi"

UserConfigDir is the per-user install's directory, under $HOME. It holds the same files an /etc/miabi install does — the manifest and, beside it, the gateway config — because everything else is resolved relative to the manifest.

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 ErrNoDocument = errors.New("no ControlPlane document found")

ErrNoDocument is returned for input that parses as YAML but holds no install document.

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 ConvertFile added in v1.10.1

func ConvertFile(path string, m *Manifest) (bool, error)

ConvertFile copies a flat manifest aside and marks m so the next Save writes the kinded document. A no-op for a manifest that is already kinded, and it never writes the new shape itself — the caller's Save does, so a converge that fails in between leaves the original copy intact.

The copy is not optional: this file is the only record of the install's secrets, and an older CLI cannot read what replaces it.

func GomaConfig

func GomaConfig() []byte

GomaConfig exposes the embedded config so the drift test can compare it.

func IsDocument added in v1.10.1

func IsDocument(b []byte) bool

IsDocument reports whether b looks like a kinded install document rather than the flat schema. It keys off apiVersion alone, so a malformed document is still reported as one and gets its own error rather than "this is not a Miabi stack manifest".

func JSONSchema added in v1.10.1

func JSONSchema() ([]byte, error)

JSONSchema renders the install document's JSON Schema from the types the parser binds to. A field the parser accepts and the schema does not is a false error in an editor; the reverse is a file that passes in the editor and fails at install. Generating it is what keeps the two identical.

func ManifestPath

func ManifestPath() string

ManifestPath resolves the manifest location: MIABI_CONFIG_FILE, else the older MIABI_STACK_FILE, else an install that already exists, else where a new one belongs for this user.

Finding an existing manifest wherever it is comes before choosing by privilege on purpose: an operator who installed with sudo and then runs a read-only command without it must not be told "not installed" while a working install sits in /etc/miabi. Only a fresh install picks a side.

func MarshalDocument added in v1.10.1

func MarshalDocument(d *Document) ([]byte, error)

MarshalDocument renders a document with the indentation the rest of the platform's YAML uses.

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.

func UserConfigPath added in v1.10.4

func UserConfigPath() string

UserConfigPath is where a non-root install keeps its manifest: ~/.miabi/miabi.yaml. Empty when there is no home directory to put it in, which is the one case the caller must handle.

Types

type ACME added in v1.10.1

type ACME struct {
	Email        string `yaml:"email,omitempty"`
	DirectoryURL string `yaml:"directoryUrl,omitempty"`
}

ACME is the certificate authority used for every acme-managed host on this install. Email is the contact Let's Encrypt sends expiry notices to, and doubles as the admin login when none is given.

type AdminSpec added in v1.10.1

type AdminSpec struct {
	Email string `yaml:"email,omitempty"`
}

AdminSpec is the first admin account. Only the address: the password is generated into spec.secrets, because this is an identity and that is a credential.

type BackupDestination added in v1.10.1

type BackupDestination struct {
	Endpoint       string `yaml:"endpoint,omitempty"`
	Bucket         string `yaml:"bucket,omitempty"`
	Region         string `yaml:"region,omitempty"`
	AccessKey      string `yaml:"accessKey,omitempty"`
	SecretKey      string `yaml:"secretKey,omitempty"`
	UseSSL         *bool  `yaml:"useSSL,omitempty"`
	ForcePathStyle *bool  `yaml:"forcePathStyle,omitempty"`
	Path           string `yaml:"path,omitempty"`
	DatabasePath   string `yaml:"databasePath,omitempty"`
	VolumePath     string `yaml:"volumePath,omitempty"`
}

BackupDestination is the S3-compatible target. Bucket, accessKey and secretKey are all-or-nothing: with any one missing the control plane ignores the whole block and leaves the console in charge.

type BackupEncryption added in v1.10.1

type BackupEncryption struct {
	Passphrase      string `yaml:"passphrase,omitempty"`
	Encrypt         *bool  `yaml:"encrypt,omitempty"`
	IncludeIdentity *bool  `yaml:"includeIdentity,omitempty"`
}

BackupEncryption seals the recovery point. The passphrase is NOT the platform's master key and must never be set to it: it protects the database that would otherwise be the only place it lived, and a real disaster is exactly when the in-platform copy is unreachable. includeIdentity seals the master key in, which is what a restore onto fresh hardware needs.

type BackupRetention added in v1.10.1

type BackupRetention struct {
	Max  int `yaml:"max,omitempty"`
	Days int `yaml:"days,omitempty"`
}

BackupRetention caps whole recovery points. Zero is unbounded.

type BackupSpec added in v1.10.1

type BackupSpec struct {
	Schedule          string            `yaml:"schedule,omitempty"`
	Destination       BackupDestination `yaml:"destination,omitempty"`
	Encryption        BackupEncryption  `yaml:"encryption,omitempty"`
	IncludeTenantData *bool             `yaml:"includeTenantData,omitempty"`
	Retention         BackupRetention   `yaml:"retention,omitempty"`
}

BackupSpec is the platform's own backup (Enterprise). Stating any of it pins the console's corresponding fields, which is the point on an install described by infrastructure-as-code.

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 DNSSpec added in v1.10.1

type DNSSpec struct {
	ReconcileMinutes int `yaml:"reconcileMinutes,omitempty"`
}

DNSSpec paces the managed-DNS re-assert sweep.

type Document added in v1.10.1

type Document struct {
	APIVersion string       `yaml:"apiVersion"`
	Kind       string       `yaml:"kind"`
	Metadata   DocumentMeta `yaml:"metadata,omitempty"`
	Spec       Spec         `yaml:"spec"`
}

Document is the install manifest's on-disk form. Manifest stays the internal representation: both this and the flat schema convert into it, so nothing downstream learns which shape was read.

func NewDocument added in v1.10.1

func NewDocument(m *Manifest) *Document

NewDocument converts a manifest into its kinded form.

func ParseDocument added in v1.10.1

func ParseDocument(b []byte) (*Document, error)

ParseDocument reads an install document. Unknown fields are refused — every other manifest parser in the platform does the same, and a silently ignored `acme_emial:` is an install with no ACME contact and no error.

func (*Document) Manifest added in v1.10.1

func (d *Document) Manifest() *Manifest

Manifest converts the document into the internal representation. Every consumer downstream of Load sees a Manifest and never learns which on-disk shape produced it.

type DocumentMeta added in v1.10.1

type DocumentMeta struct {
	Name string `yaml:"name,omitempty"`
}

DocumentMeta identifies the install. There is one per host, so the name is decoration: it labels `miabi stack status` output and nothing else. Renaming it renames nothing.

type Endpoints added in v1.10.1

type Endpoints struct {
	Web     string `yaml:"web,omitempty"`
	Control string `yaml:"control,omitempty"`
}

Endpoints are the URLs the platform answers on. Control is where nodes, agents and runners dial back, and is separate from Web because a node on a private network may reach the control plane at an address the public panel URL never resolves to.

type ExternalSpec added in v1.10.1

type ExternalSpec struct {
	BaseDomain   string `yaml:"baseDomain,omitempty"`
	CertProvider string `yaml:"certProvider,omitempty"`
}

ExternalSpec is the wildcard domain one-click application URLs are published under on the default cluster. Setting it here pins it; leave it empty to manage it from Clusters.

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 GatewaySpec added in v1.10.1

type GatewaySpec struct {
	Image  string `yaml:"image,omitempty"`
	Config string `yaml:"config,omitempty"`
	// ConfigSha is written by Miabi, never by the operator: it records the digest of the DEFAULT
	// config last written, which is what keeps a customized goma.yml from being overwritten.
	ConfigSha string            `yaml:"configSha,omitempty"`
	Env       map[string]string `yaml:"env,omitempty"`
	// TrustedProxies are the IPs or CIDRs of the proxies in front of the gateway — a CDN such as
	// Cloudflare, or a TLS-terminating load balancer. Only connections from these may set the client IP
	// through forwarded headers; leave it unset when the gateway faces the internet directly.
	TrustedProxies []string `yaml:"trustedProxies,omitempty"`
}

GatewaySpec is Goma Gateway: the image, the config file bind-mounted read-only from beside this manifest, and anything that config interpolates.

type HostPortsSpec added in v1.10.1

type HostPortsSpec struct {
	Min int `yaml:"min,omitempty"`
	Max int `yaml:"max,omitempty"`
}

HostPortsSpec bounds the host ports an application may ask to publish.

type ImageSpec added in v1.10.1

type ImageSpec struct {
	Image string `yaml:"image,omitempty"`
}

ImageSpec pins a component that has nothing to configure but the image it runs.

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 InstallSettings added in v1.10.1

type InstallSettings struct {
	ACMEDirectoryURL      string
	RegistryStorage       string
	RegistryPlatformToken string
	Pool                  PoolSpec
	HostPorts             HostPortsSpec
	External              ExternalSpec
	DNS                   DNSSpec
	Backup                *BackupSpec
	License               LicenseSpec
	GatewayTrustedProxies []string
	ServerTrustedProxies  []string
}

InstallSettings carries what only the kinded document models. It is not serialized: the flat schema never had these, and the document writer maps them field by field.

type LicenseSpec added in v1.10.1

type LicenseSpec struct {
	File string `yaml:"file,omitempty"`
}

LicenseSpec points at a signed Enterprise license on disk. It is installed only when the database holds none: a license added through the console takes precedence.

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

	// Install carries the settings only the kinded document models — the managed subnet pool, the host
	// port range, external access, the DNS interval, platform backup and the license. Not serialized:
	// the flat schema never had them, and the document writer maps them field by field.
	Install InstallSettings `yaml:"-"`
	// 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) GenerateGatewayConfigKey added in v1.10.1

func (m *Manifest) GenerateGatewayConfigKey() error

GenerateGatewayConfigKey mints the Goma config-encryption key, and is called ONLY for a fresh install.

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"`
	IPv6   *bool  `yaml:"ipv6,omitempty"`
}

type NetworkingSpec added in v1.10.1

type NetworkingSpec struct {
	Proxy     NetworkConfig `yaml:"proxy,omitempty"`
	Internal  NetworkConfig `yaml:"internal,omitempty"`
	Pool      PoolSpec      `yaml:"pool,omitempty"`
	HostPorts HostPortsSpec `yaml:"hostPorts,omitempty"`
	External  ExternalSpec  `yaml:"external,omitempty"`
	DNS       DNSSpec       `yaml:"dns,omitempty"`
}

NetworkingSpec covers the two Docker fabrics and the address policy around them: the shared proxy network routed apps join, the private one the platform talks over, and the pools and ranges Miabi allocates from. Named as a topic rather than a plural because only two of its fields are networks.

type PoolSpec added in v1.10.1

type PoolSpec struct {
	CIDR          string `yaml:"cidr,omitempty"`
	SubnetPrefix  int    `yaml:"subnetPrefix,omitempty"`
	IPv6ULAPrefix string `yaml:"ipv6UlaPrefix,omitempty"`
}

PoolSpec is the CIDR Miabi carves every managed network out of, handed to Docker as explicit IPAM so its own small default pools cannot exhaust. It must not overlap the proxy network, your LAN or a VPN.

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 RegistrySpec added in v1.10.1

type RegistrySpec struct {
	Enabled bool   `yaml:"enabled"`
	Host    string `yaml:"host,omitempty"`
	Storage string `yaml:"storage,omitempty"`
}

RegistrySpec is the built-in OCI registry. The host anchors every image reference Miabi has recorded and decides which workspace owns an image, which is why the console shows it read-only.

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 SecretsSpec added in v1.10.1

type SecretsSpec struct {
	DBPassword    string `yaml:"dbPassword,omitempty"`
	RedisPassword string `yaml:"redisPassword,omitempty"`
	JWTSecret     string `yaml:"jwtSecret,omitempty"`
	EncryptionKey string `yaml:"encryptionKey,omitempty"`
	AdminPassword string `yaml:"adminPassword,omitempty"`
	// GomaConfigEncryptionKey is the one secret here that is safe to lose: the gateway config it
	// protects is rendered from the database on every sync, so rotating it costs a converge.
	GomaConfigEncryptionKey string `yaml:"gomaConfigEncryptionKey,omitempty"`
	RegistryPlatformToken   string `yaml:"registryPlatformToken,omitempty"`
}

SecretsSpec holds the install's secrets in plaintext, as the flat schema always has. The file is mode 0600 on a root-owned host, and anyone who can read it already holds the Docker socket.

type ServerSpec added in v1.10.1

type ServerSpec struct {
	Image string `yaml:"image,omitempty"`
	// HostProc is a pointer because absent must mean on.
	HostProc  *bool  `yaml:"hostProc,omitempty"`
	DockerGid string `yaml:"dockerGid,omitempty"`
	// TrustedProxies are the IPs or CIDRs the control plane believes X-Forwarded-For and X-Real-IP from.
	// Defaults to the private network, the only one the gateway reaches it on; change it with that
	// network's subnet.
	TrustedProxies []string          `yaml:"trustedProxies,omitempty"`
	Env            map[string]string `yaml:"env,omitempty"`
}

ServerSpec is the control plane's own container: the image it runs, the read-only host /proc bind that lets the Nodes page report real host CPU and memory, and any variable Miabi reads that this document does not already model.

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) NodeGatewayImageDrift added in v1.10.6

func (s *Service) NodeGatewayImageDrift(ctx context.Context, want string) string

NodeGatewayImageDrift reports the image the running control plane is still handing to node gateways when that differs from want, or "" when they agree.

They can differ because the two live in different containers: upgrading the gateway component rewrites the manifest and recreates the gateway, while the value nodes actually follow rides the control plane's environment and is only re-rendered when THAT container is recreated. Until then every node keeps provisioning the version just upgraded away from.

A control plane that cannot be inspected reports no drift: this exists to tell an operator something useful, never to fail an upgrade that otherwise worked.

func (*Service) Pending added in v1.10.14

func (s *Service) Pending(ctx context.Context, m *Manifest) ([]string, error)

Pending names the components the next Converge would create or recreate: missing, stopped, or created from a spec the manifest no longer describes.

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.

type Spec added in v1.10.1

type Spec struct {
	Domain      string         `yaml:"domain"`
	Endpoints   Endpoints      `yaml:"endpoints,omitempty"`
	ACME        ACME           `yaml:"acme,omitempty"`
	Server      ServerSpec     `yaml:"server,omitempty"`
	Database    ImageSpec      `yaml:"database,omitempty"`
	Cache       ImageSpec      `yaml:"cache,omitempty"`
	Gateway     GatewaySpec    `yaml:"gateway,omitempty"`
	Registry    RegistrySpec   `yaml:"registry,omitempty"`
	Admin       AdminSpec      `yaml:"admin,omitempty"`
	Secrets     SecretsSpec    `yaml:"secrets,omitempty"`
	Networking  NetworkingSpec `yaml:"networking,omitempty"`
	Backup      *BackupSpec    `yaml:"backup,omitempty"`
	License     LicenseSpec    `yaml:"license,omitempty"`
	RunnerImage string         `yaml:"runnerImage,omitempty"`
}

Spec is the ControlPlane's desired state. Optional scalars that pin a console-owned setting are pointers: an emitted environment variable locks the field in the UI, so "unset" and "set to the zero value" have to stay distinguishable.

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