stackcmd

package
v1.10.24 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: AGPL-3.0, Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package stackcmd is the behaviour behind the host-side verbs — install/converge, upgrade, restart, status and uninstall — with no command-line framework attached.

Two front-ends drive it, and they must not drift:

  • `miabi setup|upgrade|stack …` in the CLI (cobra), the normal path;
  • `docker run miabi/miabi:<tag> install …` on the server image (okapicli), which is how a user without root installs — the image runs as uid 10001 with the host's docker group, so nothing has to be written to /usr/local/bin.

Each front-end owns only its flag parsing and its rendering; everything that decides what happens to a host lives here, once.

Index

Constants

View Source
const LabelPreRestore = "pre-restore"

LabelPreRestore marks the dump a restore takes of the database it replaces. Only these are pruned; a dump the operator asked for is never deleted.

Variables

This section is empty.

Functions

func Apply added in v1.10.14

func Apply(ctx context.Context, svc *stack.Service, path string, yes bool, ui UI) error

Apply converges the stack onto the manifest, recreating only the components whose spec changed. It is the second half of `env set`, so a batch of edits costs one recreate per component.

func Backup added in v1.10.21

func Backup(ctx context.Context, svc *stack.Service, path string, o BackupOptions, ui UI) (string, error)

Backup dumps the platform database. It covers the database only — not volumes, certificates or the manifest, whose encryption key the dump is useless without.

func BackupDir added in v1.10.21

func BackupDir(manifestPath string) string

BackupDir is where dumps go by default: beside the manifest, which every install already has writable and which the containerized installer already bind-mounts.

func EnvGet added in v1.10.1

func EnvGet(path, key string, o EnvOptions) (value string, found bool, err error)

EnvGet returns one variable's value. found is false when the manifest does not carry it, which the caller should report as such rather than printing an empty line.

func EnvList added in v1.10.1

func EnvList(path string, o EnvOptions) (map[string]string, string, error)

EnvList returns the environment the manifest carries, and the name of the block it came from.

func EnvSet added in v1.10.1

func EnvSet(ctx context.Context, svc *stack.Service, path string, assignments []string, o EnvOptions, ui UI) error

EnvSet writes KEY=VALUE pairs into the manifest, converging only with o.Apply. Validation is Normalize's: invalid names, variables Miabi sets itself, and settings that belong to their own spec section are all refused there, with an error that names where the value really lives.

func EnvUnset added in v1.10.1

func EnvUnset(ctx context.Context, svc *stack.Service, path string, keys []string, o EnvOptions, ui UI) error

EnvUnset removes variables. A key Miabi seeds into the manifest comes back at its default rather than disappearing, and the caller is told so — otherwise the operator diffs the file and finds the variable still there.

func Restart

func Restart(ctx context.Context, svc *stack.Service, path, component string, yes bool, ui UI) error

Restart restarts containers WITHOUT recreating them, so they re-read what is on disk. Editing the gateway's goma.yml is the obvious case (Goma watches its providers directory, not its base config); a spec change is the obvious non-case, and Service.Restart says so.

func Restore added in v1.10.21

func Restore(ctx context.Context, svc *stack.Service, path string, o RestoreOptions, ui UI) error

Restore replaces the platform database with a dump. The control plane is stopped for the swap and recreated afterwards; the current database is dumped first, so a restore can itself be undone.

func Uninstall

func Uninstall(ctx context.Context, svc *stack.Service, path string, withVolumes, yes bool, ui UI, removeFile func(string) error) error

Uninstall removes the stack's containers. Volumes are kept unless withVolumes, in which case the manifest goes too — it describes an install that no longer exists.

func Upgrade

func Upgrade(ctx context.Context, svc *stack.Service, path string, o UpgradeOptions, ui UI) error

Upgrade rolls a component to a newer image, rolling back automatically if the new one never becomes healthy. With no component named it moves the control plane and re-converges the rest.

func WithInstallHint

func WithInstallHint(err error) error

WithInstallHint turns "no manifest" into an answer rather than a dead end. The same error means very different things depending on whether Miabi is running.

Types

type BackupOptions added in v1.10.21

type BackupOptions struct {
	// Dir defaults to BackupDir.
	Dir   string
	Label string
}

BackupOptions is the flag surface of `stack backup`, already parsed.

type DBBackup added in v1.10.21

type DBBackup struct {
	Path    string
	Version string
	Label   string
	Taken   time.Time
	Size    int64
}

DBBackup is one dump found on disk.

func ListBackups added in v1.10.21

func ListBackups(dir string) ([]DBBackup, error)

ListBackups returns the dumps in dir, newest first. Files that do not follow the naming scheme are ignored rather than guessed at.

type EnvOptions added in v1.10.1

type EnvOptions struct {
	// Gateway edits the gateway's environment instead of the control plane's.
	Gateway bool
	// Apply converges right after saving. Off by default, so several edits cost one recreate
	// through Apply rather than one each.
	Apply bool
	Yes   bool
}

EnvOptions is the flag surface of the env verbs, already parsed.

type RestoreOptions added in v1.10.21

type RestoreOptions struct {
	// File is a path, or the bare name of a dump in BackupDir.
	File string
	Yes  bool
	// Force restores a dump taken by a newer Miabi than the one running.
	Force bool
}

RestoreOptions is the flag surface of `stack restore`, already parsed.

type SetupOptions

type SetupOptions struct {
	Domain, AdminEmail, ACMEEmail, ControlURL    string
	Image, GatewayImage, RunnerImage, GomaConfig string
	RegistryHost, Subnet, InternalSubnet         string
	Registry, NoHostProc, Yes                    bool
	// IPv6 gives the shared app network and every workspace network a dual-stack address space.
	IPv6 bool
	// AdminPassword is the first admin's password; empty generates one. Only a fresh install uses it.
	AdminPassword string
	DefaultImage  func() string
}

SetupOptions is the flag surface of install/setup, already parsed.

type SetupResult

type SetupResult struct {
	Manifest *stack.Manifest
	Path     string
	// NewInstall is false for a converge of an existing manifest.
	NewInstall bool
}

SetupResult reports what a Setup did, so the caller can print its own next-steps hint — the one piece of the output that legitimately differs between the two front-ends.

func Setup

func Setup(ctx context.Context, svc *stack.Service, path string, o SetupOptions, ui UI) (*SetupResult, error)

Setup installs the stack, or converges an existing install to its manifest. It is idempotent: run against an existing manifest it keeps the stored secrets, because a regenerated database password would lock the new control plane out of its own data.

type StatusReport

type StatusReport struct {
	Manifest *stack.Manifest
	Path     string
	Found    []stack.Component
	// LegacyConfig is set when the manifest is at the pre-rename path. The host IS installed —
	// saying otherwise sends its operator hunting for a Compose stack that never existed.
	LegacyConfig error
	// Unmanaged is set when containers exist but no manifest does: a Compose or hand-rolled install.
	Unmanaged bool
	// Drift lists components running an image the manifest does not pin.
	Drift []string
}

StatusReport is what status found. The caller renders it: the two front-ends draw different tables, but neither decides what is in one.

func Status

func Status(ctx context.Context, svc *stack.Service, path string) (*StatusReport, error)

Status discovers the running stack and compares it against the manifest.

type UI

type UI interface {
	Printf(format string, a ...any)
	Info(format string, a ...any)
	Success(format string, a ...any)
	Warn(format string, a ...any)
	// Confirm asks a yes/no question. It is never called when the caller passed Yes.
	Confirm(prompt string) bool
}

UI is the front-end's output. The CLI colors it; the server image prints plainly.

type UpgradeOptions

type UpgradeOptions struct {
	// Component is empty for the whole stack, else one component by name.
	Component string
	Image     string
	Version   string
	Yes       bool
	// DefaultImage is as in SetupOptions.
	DefaultImage func() string
}

UpgradeOptions is the flag surface of upgrade/update, already parsed.

Jump to

Keyboard shortcuts

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