Documentation
¶
Overview ¶
Package stack starts, stops and checks the Docker Compose stack of a workspace.
Index ¶
- Constants
- Variables
- func CompareVersions(a, b string) int
- type APICheck
- type BackupFile
- type BackupResult
- type CleanResult
- type DownResult
- type Endpoint
- type Env
- type LogLine
- type LogsOptions
- type LogsResult
- type Manifest
- type RestoreResult
- type RotateResult
- type RotateSkip
- type ServiceStatus
- type Status
- func Evaluate(cfg workspace.Config, containers []compose.Container, api *APICheck) Status
- func GetStatus(ctx context.Context, env Env, w Workspace) (Status, error)
- func Up(ctx context.Context, env Env, w Workspace, opts UpOptions) (Status, error)
- func Upgrade(ctx context.Context, env Env, gen generate.Env, w Workspace, version string, ...) (Status, error)
- type UpOptions
- type UpgradePlan
- type Workspace
Constants ¶
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.
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.
const ( Healthy = "healthy" Starting = "starting" Unhealthy = "unhealthy" Stopped = "stopped" )
Stack states.
const Image = "ghcr.io/hyland/openarch-app-jvm"
Image is the OpenArch image without its tag.
Variables ¶
var RotateTargets = []string{RotateMongoRoot, RotateMongoApp, RotateOpenSearch, RotateAdmin}
RotateTargets lists the valid targets, in the order they are rotated.
Functions ¶
func CompareVersions ¶
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 ¶
BackupResult is the outcome of Backup.
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.
type DownResult ¶
type DownResult struct {
Workspace string `json:"workspace"`
DataRemoved bool `json:"dataRemoved"`
}
DownResult is the outcome of Down.
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.
type LogLine ¶
type LogLine struct {
Service string `json:"service"`
Container string `json:"container"`
Text string `json:"text"`
}
LogLine is one parsed log line.
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 ¶
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.
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.
type RotateSkip ¶
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 ¶
Evaluate combines the containers and the API check into a status. api is nil when the check did not run.
func GetStatus ¶
GetStatus returns the state of the stack, with an API check when OpenArch is running.
func Up ¶
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.
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.
type Workspace ¶
Workspace is a loaded workspace.
func (Workspace) ConfigHashes ¶
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.