stack

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package stack starts, stops and checks the Docker Compose stack of a workspace.

Index

Constants

View Source
const (
	ManifestFile   = "manifest.json"
	MongoFile      = "mongodb.archive.gz"
	FilesFile      = "files.tar.gz"
	OpenSearchFile = "opensearch.tar.gz"
	// BackupsDir is the default folder of backups in a workspace.
	BackupsDir = "backups"
	// IndexPattern matches the OpenSearch indices of OpenArch (index name "nuxeo" and its
	// _configuration, _embeddings and _vocabularies companions, the OpenArch defaults).
	IndexPattern = "nuxeo*"
	// BackupFormat is the version of the backup layout.
	BackupFormat = 1
)

Backup file names.

View Source
const (
	RotateAdmin      = "admin"        // OpenArch admin
	RotateMongoRoot  = "mongodb-root" // MongoDB root user
	RotateMongoApp   = "mongodb-app"  // MongoDB user of OpenArch
	RotateOpenSearch = "opensearch"   // OpenSearch users admin, openarch and kibanaserver
)

Secrets that 'secrets rotate' can change.

View Source
const (
	Healthy   = "healthy"
	Starting  = "starting"
	Unhealthy = "unhealthy"
	Stopped   = "stopped"
)

Stack states.

View Source
const Image = "ghcr.io/hyland/openarch-app-jvm"

Image is the OpenArch image without its tag.

Variables

RotateTargets lists the valid targets, in the order they are rotated.

Functions

func CompareVersions

func CompareVersions(a, b string) int

CompareVersions compares dotted numeric versions such as 1.0.55. It returns 0 when a version is not numeric (for example "latest"): the order is unknown.

Types

type APICheck

type APICheck struct {
	URL        string `json:"url"`
	OK         bool   `json:"ok"`
	StatusCode int    `json:"statusCode,omitempty"`
	Error      string `json:"error,omitempty"`
}

APICheck is the result of an HTTP request to the OpenArch health endpoint.

type BackupFile

type BackupFile struct {
	Name   string `json:"name"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

BackupFile is one file of a backup.

type BackupResult

type BackupResult struct {
	Path     string   `json:"path"`
	Manifest Manifest `json:"manifest"`
}

BackupResult is the outcome of Backup.

func Backup

func Backup(ctx context.Context, env Env, w Workspace, parent string, progress io.Writer) (BackupResult, error)

Backup writes a backup of MongoDB, the OpenArch files and the OpenSearch indices into a new folder in parent. The stack must be running.

func (BackupResult) WriteText

func (r BackupResult) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type CleanResult

type CleanResult struct {
	Workspace string `json:"workspace"`
	// DataFolder is set with storage bind: Clean does not delete it.
	DataFolder string `json:"dataFolder,omitempty"`
}

CleanResult is the outcome of Clean.

func Clean

func Clean(ctx context.Context, env Env, w Workspace, progress io.Writer) (CleanResult, error)

Clean stops the stack and deletes its containers, network and volumes. The data folders of storage bind are not deleted.

func (CleanResult) WriteText

func (c CleanResult) WriteText(out io.Writer) error

WriteText writes the human-readable form.

type DownResult

type DownResult struct {
	Workspace   string `json:"workspace"`
	DataRemoved bool   `json:"dataRemoved"`
}

DownResult is the outcome of Down.

func Down

func Down(ctx context.Context, env Env, w Workspace, progress io.Writer) (DownResult, error)

Down stops and removes the containers. Named volumes and data folders are kept. With storage none, the anonymous volumes are removed too, as that mode keeps no data.

func (DownResult) WriteText

func (d DownResult) WriteText(out io.Writer) error

WriteText writes the human-readable form.

type Endpoint

type Endpoint struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

Endpoint is a URL a user can open.

func Endpoints

func Endpoints(cfg workspace.Config) []Endpoint

Endpoints returns the URLs of the workspace.

type Env

type Env struct {
	Compose compose.Exec
	Doctor  func() doctor.Env
	// CheckAPI calls the OpenArch health endpoint of a workspace.
	CheckAPI func(ctx context.Context, dir string, cfg workspace.Config) APICheck
}

Env is the access to the system. Tests replace it with fakes.

func SystemEnv

func SystemEnv() Env

SystemEnv returns an Env backed by the real system.

type LogLine

type LogLine struct {
	Service   string `json:"service"`
	Container string `json:"container"`
	Text      string `json:"text"`
}

LogLine is one parsed log line.

func ParseLogs

func ParseLogs(data []byte) []LogLine

ParseLogs splits 'docker compose logs --no-color' output, where each line starts with "<container> | ".

type LogsOptions

type LogsOptions struct {
	Services []string
	Follow   bool
	Tail     string
	Since    string
	// Stream receives the log lines as text. When nil, Logs returns them parsed.
	Stream io.Writer
	Stderr io.Writer
}

LogsOptions are the inputs of Logs.

type LogsResult

type LogsResult struct {
	Lines []LogLine `json:"lines"`
}

LogsResult holds parsed log lines, for JSON output.

func Logs

func Logs(ctx context.Context, env Env, w Workspace, opts LogsOptions) (LogsResult, error)

Logs shows the logs of some or all services.

type Manifest

type Manifest struct {
	Format           int          `json:"format"`
	Created          time.Time    `json:"created"`
	Workspace        string       `json:"workspace"`
	OpenArchVersion  string       `json:"openarchVersion"`
	InsecureBackends bool         `json:"insecureBackends,omitempty"`
	Files            []BackupFile `json:"files"`
}

Manifest describes a backup.

func ReadManifest

func ReadManifest(dir string) (Manifest, error)

ReadManifest reads and checks a backup: every file must exist and match its hash.

type RestoreResult

type RestoreResult struct {
	Backup   string   `json:"backup"`
	Manifest Manifest `json:"manifest"`
	Status   Status   `json:"status"`
}

RestoreResult is the outcome of Restore.

func Restore

func Restore(ctx context.Context, env Env, w Workspace, dir string, opts UpOptions) (RestoreResult, error)

Restore replaces the data of the workspace with a backup, then starts the stack. It checks the backup before it changes anything.

func (RestoreResult) WriteText

func (r RestoreResult) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type RotateResult

type RotateResult struct {
	Workspace string       `json:"workspace"`
	Rotated   []string     `json:"rotated"`
	Skipped   []RotateSkip `json:"skipped,omitempty"`
	// Applied is false when the stack was not running: the new passwords apply at the next 'openarch up'.
	Applied bool    `json:"applied"`
	Status  *Status `json:"status,omitempty"`
}

RotateResult is the outcome of Rotate. It never holds a password.

func Rotate

func Rotate(ctx context.Context, env Env, gen generate.Env, w Workspace, targets []string, opts UpOptions) (RotateResult, error)

Rotate gives new passwords to the selected secrets. Each live change is made first, and .env.local is saved right after it, so the file always matches what the services accept. Then the workspace is rendered and, when the stack runs, 'up' recreates the services whose secrets changed.

func (RotateResult) WriteText

func (r RotateResult) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type RotateSkip

type RotateSkip struct {
	Target string `json:"target"`
	Reason string `json:"reason"`
}

RotateSkip is a target that was not rotated, and why.

func RotatePlan

func RotatePlan(w Workspace, targets []string) ([]string, []RotateSkip, error)

RotatePlan checks the targets and returns the ones to rotate and the ones to skip.

type ServiceStatus

type ServiceStatus struct {
	Name string `json:"name"`
	// State is the container state from Docker (running, exited, ...), or "missing".
	State string `json:"state"`
	// Health is the Docker healthcheck result (healthy, starting, unhealthy), or "" when the service has none.
	Health   string `json:"health,omitempty"`
	ExitCode int    `json:"exitCode"`
	OneShot  bool   `json:"oneShot"`
	Ports    []int  `json:"ports,omitempty"`
	// OK reports whether this service is in its expected final state.
	OK bool `json:"ok"`
}

ServiceStatus is the state of one service.

type Status

type Status struct {
	Workspace string          `json:"workspace"`
	State     string          `json:"state"`
	Services  []ServiceStatus `json:"services"`
	API       *APICheck       `json:"api,omitempty"`
	Endpoints []Endpoint      `json:"endpoints"`
	AdminUser string          `json:"adminUser,omitempty"`
	// Command is the CLI command that produced the status, for the text form.
	Command string `json:"-"`
}

Status is the state of the whole stack.

func Evaluate

func Evaluate(cfg workspace.Config, containers []compose.Container, api *APICheck) Status

Evaluate combines the containers and the API check into a status. api is nil when the check did not run.

func GetStatus

func GetStatus(ctx context.Context, env Env, w Workspace) (Status, error)

GetStatus returns the state of the stack, with an API check when OpenArch is running.

func Up

func Up(ctx context.Context, env Env, w Workspace, opts UpOptions) (Status, error)

Up checks the prerequisites, starts the stack and, with Wait, waits until it is healthy. A stack that is not healthy in time gives a status and an error with exit code 4.

func Upgrade

func Upgrade(ctx context.Context, env Env, gen generate.Env, w Workspace, version string, opts UpOptions) (Status, error)

Upgrade pulls the new image, then writes the new version, renders the workspace and starts the stack. The workspace files change only after the pull worked, so a tag that does not exist changes nothing.

func (Status) WriteText

func (s Status) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type UpOptions

type UpOptions struct {
	SkipDoctor bool
	Wait       bool
	Timeout    time.Duration
	// Progress receives the output of docker compose.
	Progress io.Writer
}

UpOptions are the inputs of Up.

type UpgradePlan

type UpgradePlan struct {
	Workspace string   `json:"workspace"`
	From      string   `json:"from"`
	To        string   `json:"to"`
	Steps     []string `json:"steps"`
	// Downgrade is true when To is an older version than From.
	Downgrade bool `json:"downgrade"`
}

UpgradePlan describes an upgrade.

func PlanUpgrade

func PlanUpgrade(w Workspace, version string, smoke bool) (UpgradePlan, error)

PlanUpgrade returns the steps of an upgrade to version, or a usage error.

func (UpgradePlan) WriteText

func (p UpgradePlan) WriteText(w io.Writer) error

WriteText writes the human-readable form.

type Workspace

type Workspace struct {
	Dir     string
	Config  workspace.Config
	Secrets localenv.Env
}

Workspace is a loaded workspace.

func Load

func Load(dir string) (Workspace, error)

Load reads openarch.yaml and .env.local from dir.

func (Workspace) ConfigHashes

func (w Workspace) ConfigHashes() []string

ConfigHashes returns the hash variables of the compose.yaml labels. Each hash covers the files and secrets a service reads only at start, which Docker Compose cannot see change by itself.

Jump to

Keyboard shortcuts

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