system

package
v2.10.2 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2026 License: BSD-3-Clause Imports: 64 Imported by: 0

Documentation

Overview

Package system owns Docker system-wide operations — prune, disk usage, host info — and the HTTP surface that exposes them.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterSystem 

func RegisterSystem(api huma.API, dockerService *docker.DockerClientService, systemService *SystemService, upgradeService *SystemUpgradeService, environmentService *environment.EnvironmentService, cfg *config.Config, activityService *activity.ActivityService, appCtx handlerutil.ActivityAppContext)

RegisterSystem registers system management endpoints using Huma. WebSocket statistics endpoints live in api/ws.

func ResolveUpgraderRuntimeOptions added in v2.9.0 

func ResolveUpgraderRuntimeOptions(
	ctx context.Context,
	dockerHost string,
	currentContainer *container.InspectResponse,
	discoverHostPath func(context.Context, string) (string, error),
	isRunningInDocker func() bool,
	selectReachableNetwork func(context.Context, *container.InspectResponse, string) string,
) ([]string, []mount.Mount, container.NetworkMode, error)

ResolveUpgraderRuntimeOptions determines how a helper container reaches the Docker daemon.

Types

type CheckUpgradeInput 

type CheckUpgradeInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type CheckUpgradeOutput 

type CheckUpgradeOutput struct {
	Body UpgradeCheckResultData
}

type ConvertDockerRunInput 

type ConvertDockerRunInput struct {
	EnvironmentID string                         `path:"id" doc:"Environment ID"`
	Body          system.ConvertDockerRunRequest `doc:"Docker run command"`
}

type ConvertDockerRunOutput 

type ConvertDockerRunOutput struct {
	Body system.ConvertDockerRunResponse
}

type Dependencies 

type Dependencies struct {
	DB            *database.DB
	Config        *config.Config
	Docker        *docker.DockerClientService
	Container     *container.ContainerService
	Image         *image.ImageService
	Volume        *volume.VolumeService
	Network       *network.NetworkService
	Settings      *settings.SettingsService
	Activity      *activity.ActivityService
	SystemUpgrade *SystemUpgradeService
	Environment   *environment.EnvironmentService
}

Dependencies are the collaborators the system domain needs.

type EnvironmentUpdateJob added in v2.8.1 

type EnvironmentUpdateJob struct {
	database.BaseModel

	Status                EnvironmentUpdateJobStatus `json:"status" gorm:"column:status"`
	UserID                string                     `json:"userId" gorm:"column:user_id"`
	Username              string                     `json:"username" gorm:"column:username"`
	ManagerVersionAtStart string                     `json:"managerVersionAtStart" gorm:"column:manager_version_at_start"`
	ManagerDigestAtStart  string                     `json:"managerDigestAtStart" gorm:"column:manager_digest_at_start"`
	ManagerTargetVersion  string                     `json:"managerTargetVersion" gorm:"column:manager_target_version"`
	Results               EnvironmentUpdateResults   `json:"results,omitempty" gorm:"column:results;type:text"`
	Error                 *string                    `json:"error,omitempty" gorm:"column:error"`
	CompletedAt           *time.Time                 `json:"completedAt,omitempty" gorm:"column:completed_at"`
}

EnvironmentUpdateJob is a persisted fleet-wide update orchestration record. It survives the manager's final self-upgrade restart so the manager result can be finalized on the next boot. See EnvironmentUpdateJobStatus.

func (EnvironmentUpdateJob) TableName added in v2.8.1 

func (EnvironmentUpdateJob) TableName() string

type EnvironmentUpdateJobStatus added in v2.8.1 

type EnvironmentUpdateJobStatus string

EnvironmentUpdateJobStatus is the lifecycle status of a fleet-wide "update all environments" job. 

const (
	// EnvironmentUpdateJobStatusPendingRestart means the remote agents have been
	// updated and the manager has triggered its own self-upgrade as the final step;
	// it is waiting to restart on the new version, after which the job is finalized.
	EnvironmentUpdateJobStatusPendingRestart EnvironmentUpdateJobStatus = "pending_restart"
	// EnvironmentUpdateJobStatusRunning means the agents phase is in progress.
	EnvironmentUpdateJobStatusRunning EnvironmentUpdateJobStatus = "running"
	// EnvironmentUpdateJobStatusCompleted means every environment has been processed.
	EnvironmentUpdateJobStatusCompleted EnvironmentUpdateJobStatus = "completed"
	// EnvironmentUpdateJobStatusFailed means the job stopped before completing.
	EnvironmentUpdateJobStatusFailed EnvironmentUpdateJobStatus = "failed"
)

type EnvironmentUpdateResult added in v2.8.1 

type EnvironmentUpdateResult struct {
	EnvironmentID   string                        `json:"environmentId"`
	EnvironmentName string                        `json:"environmentName"`
	Status          EnvironmentUpdateResultStatus `json:"status"`
	FromVersion     string                        `json:"fromVersion,omitempty"`
	ToVersion       string                        `json:"toVersion,omitempty"`
	Error           string                        `json:"error,omitempty"`
}

EnvironmentUpdateResult is the outcome for a single environment within a job. The manager appears as the first entry with EnvironmentID "0".

type EnvironmentUpdateResultStatus added in v2.8.1 

type EnvironmentUpdateResultStatus string

EnvironmentUpdateResultStatus is the per-environment outcome within a job. 

const (
	// EnvironmentUpdateResultStatusPending is the initial state recorded for an
	// environment that is seeded into the job but not yet being processed (and for
	// the manager entry while its self-upgrade is in flight).
	EnvironmentUpdateResultStatusPending EnvironmentUpdateResultStatus = "pending"
	// EnvironmentUpdateResultStatusUpdating means this environment is being processed
	// right now; it drives the live per-environment progress indicator in the UI.
	EnvironmentUpdateResultStatusUpdating EnvironmentUpdateResultStatus = "updating"
	// EnvironmentUpdateResultStatusUpdated means the upgrade was triggered and the
	// new version was confirmed.
	EnvironmentUpdateResultStatusUpdated EnvironmentUpdateResultStatus = "updated"
	// EnvironmentUpdateResultStatusTriggered means the upgrade was triggered but not
	// confirmed within the wait window (still likely succeeding in the background).
	EnvironmentUpdateResultStatusTriggered EnvironmentUpdateResultStatus = "triggered"
	// EnvironmentUpdateResultStatusUpToDate means the environment already ran the
	// target image, so the pull found nothing new and no container was recreated.
	EnvironmentUpdateResultStatusUpToDate EnvironmentUpdateResultStatus = "up_to_date"
	// EnvironmentUpdateResultStatusSkippedOffline means the environment was unreachable.
	EnvironmentUpdateResultStatusSkippedOffline EnvironmentUpdateResultStatus = "skipped_offline"
	// EnvironmentUpdateResultStatusFailed means the upgrade trigger failed.
	EnvironmentUpdateResultStatusFailed EnvironmentUpdateResultStatus = "failed"
)

type EnvironmentUpdateResults added in v2.8.1 

type EnvironmentUpdateResults []EnvironmentUpdateResult

EnvironmentUpdateResults is a JSON-serialized slice of per-environment results, stored in a single TEXT column.

func (*EnvironmentUpdateResults) Scan added in v2.8.1 

func (r *EnvironmentUpdateResults) Scan(value any) error

func (EnvironmentUpdateResults) Value added in v2.8.1 

func (r EnvironmentUpdateResults) Value() (driver.Value, error)

type GetDockerInfoInput 

type GetDockerInfoInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type GetDockerInfoOutput 

type GetDockerInfoOutput struct {
	Body dockerinfo.Info
}

type Module 

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

Module wires the system domain and mounts its routes.

func New 

func New(deps Dependencies) *Module

New builds the system domain from its dependencies.

func (*Module) RegisterRoutes 

func (m *Module) RegisterRoutes(api huma.API, appCtx handlerutil.ActivityAppContext)

RegisterRoutes mounts the system endpoints. A nil module still registers, so OpenAPI spec generation can discover the routes without a service graph.

func (*Module) Service 

func (m *Module) Service() *SystemService

Service exposes the system service to collaborators that need it directly, such as the scheduled prune job.

type PruneAllInput 

type PruneAllInput struct {
	EnvironmentID string                 `path:"id" doc:"Environment ID"`
	Body          system.PruneAllRequest `doc:"Prune options"`
}

type StartAllContainersInput 

type StartAllContainersInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type StartAllStoppedContainersInput 

type StartAllStoppedContainersInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type StopAllContainersInput 

type StopAllContainersInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type SystemHandler 

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

SystemHandler handles system management endpoints.

func (*SystemHandler) CheckUpgradeAvailable 

func (h *SystemHandler) CheckUpgradeAvailable(ctx context.Context, input *CheckUpgradeInput) (*CheckUpgradeOutput, error)

CheckUpgradeAvailable checks if a system upgrade is available.

func (*SystemHandler) ConvertDockerRun 

func (h *SystemHandler) ConvertDockerRun(ctx context.Context, input *ConvertDockerRunInput) (*ConvertDockerRunOutput, error)

ConvertDockerRun converts a docker run command to docker-compose format.

func (*SystemHandler) GetDockerInfo 

func (h *SystemHandler) GetDockerInfo(ctx context.Context, input *GetDockerInfoInput) (*GetDockerInfoOutput, error)

GetDockerInfo returns Docker daemon version and system information.

func (*SystemHandler) GetUpdateAllStatus 

func (h *SystemHandler) GetUpdateAllStatus(ctx context.Context, input *UpdateAllStatusInput) (*handlerutil.Out[EnvironmentUpdateJob], error)

GetUpdateAllStatus returns the latest update-all job for live progress polling.

func (*SystemHandler) Health 

func (h *SystemHandler) Health(ctx context.Context, input *SystemHealthInput) (*struct{}, error)

Health checks if the Docker daemon is responsive.

func (*SystemHandler) PruneAll 

func (h *SystemHandler) PruneAll(ctx context.Context, input *PruneAllInput) (*handlerutil.Out[system.PruneAllResult], error)

PruneAll removes unused Docker resources.

func (*SystemHandler) StartAllContainers 

func (h *SystemHandler) StartAllContainers(ctx context.Context, input *StartAllContainersInput) (*handlerutil.Out[containertypes.ActionResult], error)

StartAllContainers starts all Docker containers.

func (*SystemHandler) StartAllStoppedContainers 

func (h *SystemHandler) StartAllStoppedContainers(ctx context.Context, input *StartAllStoppedContainersInput) (*handlerutil.Out[containertypes.ActionResult], error)

StartAllStoppedContainers starts all stopped Docker containers.

func (*SystemHandler) StopAllContainers 

func (h *SystemHandler) StopAllContainers(ctx context.Context, input *StopAllContainersInput) (*handlerutil.Out[containertypes.ActionResult], error)

StopAllContainers stops all running Docker containers.

func (*SystemHandler) TriggerUpdateAll 

func (h *SystemHandler) TriggerUpdateAll(ctx context.Context, input *TriggerUpdateAllInput) (*handlerutil.Out[EnvironmentUpdateJob], error)

TriggerUpdateAll starts a fleet-wide update, upgrading the manager first and then the remote agents (the latter resume after the manager restarts).

func (*SystemHandler) TriggerUpgrade 

func (h *SystemHandler) TriggerUpgrade(ctx context.Context, input *TriggerUpgradeInput) (*handlerutil.Out[TriggerUpgradeData], error)

TriggerUpgrade triggers a system upgrade.

type SystemHealthInput 

type SystemHealthInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type SystemService 

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

func NewSystemService 

func NewSystemService(
	db *database.DB,
	dockerService *docker.DockerClientService,
	containerService *container.ContainerService,
	imageService *image.ImageService,
	volumeService *volume.VolumeService,
	networkService *network.NetworkService,
	settingsService *settings.SettingsService,
	activityService *activity.ActivityService,
) *SystemService

func (*SystemService) GetDiskUsagePath 

func (s *SystemService) GetDiskUsagePath(ctx context.Context) string

func (*SystemService) GetDockerHostMemory added in v2.10.2 

func (s *SystemService) GetDockerHostMemory(ctx context.Context) (uint64, uint64, bool)

GetDockerHostMemory reports enclosing guest memory when Docker shares its host's cgroup namespace. A false result leaves the caller's baseline intact.

func (*SystemService) PruneAll 

func (s *SystemService) PruneAll(ctx context.Context, environmentID string, req system.PruneAllRequest) (*system.PruneAllResult, bool, error)

func (*SystemService) StartAllContainers 

func (s *SystemService) StartAllContainers(ctx context.Context, environmentID string) (*containertypes.ActionResult, error)

func (*SystemService) StartAllStoppedContainers 

func (s *SystemService) StartAllStoppedContainers(ctx context.Context, environmentID string) (*containertypes.ActionResult, error)

func (*SystemService) StartPruneAll 

func (s *SystemService) StartPruneAll(ctx context.Context, environmentID string, req system.PruneAllRequest) *system.PruneAllResult

func (*SystemService) StopAllContainers 

func (s *SystemService) StopAllContainers(ctx context.Context, environmentID string) (*containertypes.ActionResult, error)

type SystemUpgradeService 

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

func NewSystemUpgradeService 

func NewSystemUpgradeService(
	db *database.DB,
	dockerService *docker.DockerClientService,
	versionService *version.VersionService,
	eventService *event.EventService,
	settingsService *settings.SettingsService,
) *SystemUpgradeService

func (*SystemUpgradeService) AlreadyOnNewestImage 

func (s *SystemUpgradeService) AlreadyOnNewestImage(ctx context.Context) bool

AlreadyOnNewestImage reports whether this environment's version check is confident it already runs the newest image. A triggered upgrade still pulls, but will then find nothing to swap in and skip the recreate — so callers can use this to stop waiting for a restart that is not coming.

func (*SystemUpgradeService) CanUpgrade 

func (s *SystemUpgradeService) CanUpgrade(ctx context.Context) (bool, error)

CanUpgrade checks if self-upgrade is possible

func (*SystemUpgradeService) GetLatestUpdateAllJob 

func (s *SystemUpgradeService) GetLatestUpdateAllJob(ctx context.Context) (*EnvironmentUpdateJob, error)

GetLatestUpdateAllJob returns the most recently created update-all job, or nil.

func (*SystemUpgradeService) ResumeUpdateAllOnStartup 

func (s *SystemUpgradeService) ResumeUpdateAllOnStartup(ctx context.Context)

ResumeUpdateAllOnStartup is called once at manager startup. When the manager self-upgraded as the final step of an update-all (job left pending_restart), the agents phase already ran before the restart — so this finalizes the manager's own result and closes the job. It is a no-op when there is nothing pending.

func (*SystemUpgradeService) StartUpdateAll 

func (s *SystemUpgradeService) StartUpdateAll(ctx context.Context, user common.User, env *environment.EnvironmentService) (*EnvironmentUpdateJob, error)

StartUpdateAll begins a fleet-wide update. The agents phase runs first in the background (while the manager is up); the agents goroutine triggers the manager self-upgrade as its final step (job left pending_restart, finalized at next boot). Every environment pulls the latest image, whether or not it reports an update available.

func (*SystemUpgradeService) TriggerUpgradeAsync added in v2.10.0 

func (s *SystemUpgradeService) TriggerUpgradeAsync(ctx context.Context, user common.User, targetVersion string) error

TriggerUpgradeAsync validates synchronously, then pulls and spawns the upgrader in the background (#3628). The run follows the app lifecycle with a deadline so a stalled daemon cannot hold the upgrading guard forever.

func (*SystemUpgradeService) TriggerUpgradeViaCLI 

func (s *SystemUpgradeService) TriggerUpgradeViaCLI(ctx context.Context, user common.User, target updater.SelfUpdateTarget) (string, error)

TriggerUpgradeViaCLI spawns the upgrade CLI command in a separate container and returns that upgrader container's ID. This avoids self-termination issues by running the upgrade from outside. A zero-value target resolves the image to upgrade to from the version check (see resolveSelfUpgradeTargetImageInternal); the updater engine passes an explicit target with the resolved new image, which is used as-is. Update-all uses the returned ID to tell an upgrade that recreated this container from one that found nothing to do — see watchManagerUpgraderInternal.

type TriggerUpdateAllInput 

type TriggerUpdateAllInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type TriggerUpgradeBody added in v2.10.0 

type TriggerUpgradeBody struct {
	TargetVersion string `json:"targetVersion,omitempty" doc:"Release version to upgrade to; overrides this instance's own version check"`
}

type TriggerUpgradeData 

type TriggerUpgradeData struct {
	Message  string `json:"message" doc:"Response message"`
	UpToDate bool   `json:"upToDate" doc:"Environment already runs the newest image, so no restart is expected"`
}

TriggerUpgradeData reports the upgrade was accepted. UpToDate lets a client skip waiting for a restart: the upgrader still pulls, but when the environment already runs the newest image it finds nothing to swap in and no restart follows.

type TriggerUpgradeInput 

type TriggerUpgradeInput struct {
	EnvironmentID string              `path:"id" doc:"Environment ID"`
	Body          *TriggerUpgradeBody `doc:"Optional upgrade parameters"`
}

type UpdateAllStatusInput 

type UpdateAllStatusInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type UpgradeCheckResultData 

type UpgradeCheckResultData struct {
	CanUpgrade bool   `json:"canUpgrade"`
	Error      bool   `json:"error"`
	Message    string `json:"message"`
}

UpgradeCheckResultData is the response for upgrade check.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.