homelab

package
v0.97.8 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package homelab provides homelab application scanning and registry.

Index

Constants

View Source 
const (
	CapKarakeep = "karakeep"
	CapMiniflux = "miniflux"
	CapKanboard = "kanboard"
	CapTrilium  = "trilium"
	CapMemos    = "memos"
	CapGitea    = "gitea"
	CapGithub   = "github"
	CapExample  = "example"
	CapDevops   = "devops"

	// Discovery-only capabilities (no 1:1 pkg/capability/<provider> package).
	CapArchive      = "archive"
	CapFinance      = "finance"
	CapInfra        = "infra"
	CapShellHistory = "shell_history"
)

Capability type string constants used for label-based and probe-based discovery. Provider-backed values match pkg/hub Cap* constants.

View Source 
const (
	LabelCapability        = "flowbot.capability"
	LabelBackend           = "flowbot.backend" // deprecated: ignored; CapType is provider ID
	LabelEndpointBase      = "flowbot.endpoint.base"
	LabelEndpointHealth    = "flowbot.endpoint.health"
	LabelEndpointHealthTTL = "flowbot.endpoint.health_ttl"
	LabelAuthType          = "flowbot.auth.type"
	LabelAuthHeader        = "flowbot.auth.header"
	LabelAuthPrefix        = "flowbot.auth.prefix"
	LabelAuthTokenKey      = "flowbot.auth.token_key"
	LabelAuthTokenSource   = "flowbot.auth.token_source"
)

Label key constants for the flowbot docker-compose label convention.

Variables

View Source 
var DefaultRegistry = NewRegistry()

DefaultRegistry is the process-wide registry instance.

Functions

func AllowsLifecycle added in v0.97.8 

func AllowsLifecycle(perm Permissions, operation string) bool

AllowsLifecycle reports whether operation is permitted by config permissions. Known operations: status, logs, start, stop, restart, pull, update.

func AppVersion 

func AppVersion(app App) string

AppVersion extracts the application version from the first service that has a tagged image. Returns an empty string if no tag is found.

func LoadRunRescan added in v0.93.0 

func LoadRunRescan() func() error

LoadRunRescan returns the currently registered rescan function, or nil.

func ParseCompose 

func ParseCompose(data []byte) ([]ComposeService, []string, []PortMapping, map[string]string, error)

ParseCompose parses a Docker Compose YAML document and returns the extracted services, network names, aggregated port mappings, and merged labels.

func ParseImageVersion 

func ParseImageVersion(image string) string

ParseImageVersion extracts the version tag from a Docker image reference. Returns the portion after the last colon if present and represents a tag (not a registry port); returns an empty string when there is no valid tag or the image uses a digest reference (@sha256:...).

func RunRescan 

func RunRescan() error

RunRescan triggers a full homelab scan + probe + registry update. Returns nil if no rescan function has been registered.

func SetRunRescan added in v0.93.0 

func SetRunRescan(fn func() error)

SetRunRescan registers the function used to trigger a full homelab rescan. Safe for concurrent use.

Types

type App 

type App struct {
	Name        string            `json:"name"`
	Path        string            `json:"path"`
	ComposeFile string            `json:"compose_file"`
	Services    []ComposeService  `json:"services,omitzero"`
	Networks    []string          `json:"networks,omitzero"`
	Ports       []PortMapping     `json:"ports,omitzero"`
	Labels      map[string]string `json:"labels,omitzero"`
	Status      AppStatus         `json:"status"`
	Health      HealthStatus      `json:"health"`
	// Capabilities discovered from labels and/or probing.
	Capabilities []AppCapability `json:"capabilities,omitzero"`
}

App represents a discovered homelab application with its compose metadata, runtime status, and any capabilities derived from labels or probing.

type AppCapability 

type AppCapability struct {
	Capability string        `json:"capability"`
	Endpoint   *EndpointInfo `json:"endpoint,omitzero"`
	Auth       *AuthInfo     `json:"auth,omitzero"`
}

AppCapability links a homelab app to a capability and carries discovered endpoint and authentication metadata for automatic binding.

func ParseLabels 

func ParseLabels(labels map[string]string) []AppCapability

ParseLabels extracts AppCapability entries from the labels map using the flowbot label convention. Returns nil when no capability label is present or the capability value is not recognised.

type AppStatus 

type AppStatus string

AppStatus indicates the aggregate running state of an app's containers. 

const (
	AppStatusUnknown AppStatus = "unknown"
	AppStatusRunning AppStatus = "running"
	AppStatusStopped AppStatus = "stopped"
	AppStatusPartial AppStatus = "partial"
)

type AuthInfo 

type AuthInfo struct {
	Type        AuthType `json:"type"`
	Header      string   `json:"header,omitzero"`
	Prefix      string   `json:"prefix,omitzero"`
	TokenKey    string   `json:"token_key,omitzero"`
	TokenSource string   `json:"token_source,omitzero"`
}

AuthInfo describes the authentication mechanism discovered for an endpoint.

type AuthType 

type AuthType string

AuthType identifies the authentication mechanism used by an API endpoint. 

const (
	AuthNone     AuthType = "none"
	AuthAPIToken AuthType = "api_token"
	AuthBasic    AuthType = "basic"
	AuthOAuth2   AuthType = "oauth2"
	AuthOIDC     AuthType = "oidc"
	AuthUnknown  AuthType = "unknown"
)

type ComposeService 

type ComposeService struct {
	Name      string        `json:"name"`
	Image     string        `json:"image,omitzero"`
	Container string        `json:"container,omitzero"`
	Ports     []PortMapping `json:"ports,omitzero"`
}

ComposeService describes a single service entry within a Docker Compose file.

type Config 

type Config struct {
	Root        string
	AppsDir     string
	ComposeFile string
	Allowlist   []string
	Runtime     RuntimeConfig
	Permissions Permissions
	Discovery   DiscoveryConfig
}

Config controls how the homelab scanner discovers applications and configures the runtime and permission model.

type DiscoveryConfig 

type DiscoveryConfig struct {
	ProbeEnabled       bool          `json:"probe_enabled"`
	ProbeTimeout       time.Duration `json:"probe_timeout"`
	ProbeConcurrency   int           `json:"probe_concurrency"`
	ProbeNetworks      []string      `json:"probe_networks,omitzero"`
	ProbePortStrategy  string        `json:"probe_port_strategy"`
	FingerprintEnabled bool          `json:"fingerprint_enabled"`
	LabelPriority      bool          `json:"label_priority"`
}

DiscoveryConfig controls the behaviour of runtime endpoint discovery probing.

type DockerComposeRuntime 

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

DockerComposeRuntime executes docker compose commands locally using the Docker CLI against a configured Docker socket.

func NewDockerComposeRuntime 

func NewDockerComposeRuntime(config RuntimeConfig, appsDir string) *DockerComposeRuntime

NewDockerComposeRuntime creates a DockerComposeRuntime that shells out to docker compose using the configured socket path.

func (*DockerComposeRuntime) Logs 

func (r *DockerComposeRuntime) Logs(ctx context.Context, app App, tail int) ([]string, error)

func (*DockerComposeRuntime) Pull 

func (r *DockerComposeRuntime) Pull(ctx context.Context, app App) error

func (*DockerComposeRuntime) Restart 

func (r *DockerComposeRuntime) Restart(ctx context.Context, app App) error

func (*DockerComposeRuntime) Start 

func (r *DockerComposeRuntime) Start(ctx context.Context, app App) error

func (*DockerComposeRuntime) Status 

func (r *DockerComposeRuntime) Status(ctx context.Context, app App) (AppStatus, error)

func (*DockerComposeRuntime) Stop 

func (r *DockerComposeRuntime) Stop(ctx context.Context, app App) error

func (*DockerComposeRuntime) Update 

func (r *DockerComposeRuntime) Update(ctx context.Context, app App) error

type EndpointInfo 

type EndpointInfo struct {
	BaseURL   string        `json:"base_url"`
	Health    string        `json:"health,omitzero"`
	HealthTTL time.Duration `json:"health_ttl,omitzero"`
	Ports     []int         `json:"ports,omitzero"`
}

EndpointInfo describes a discovered API endpoint on an app service.

type HealthStatus 

type HealthStatus string

HealthStatus indicates the observed health of an app. 

const (
	HealthUnknown   HealthStatus = "unknown"
	HealthHealthy   HealthStatus = "healthy"
	HealthUnhealthy HealthStatus = "unhealthy"
)

type NoopRuntime 

type NoopRuntime struct{}

NoopRuntime is a Runtime that returns not-implemented errors for all mutating operations and preserves the existing status on reads.

func (NoopRuntime) Logs 

func (NoopRuntime) Logs(ctx context.Context, _ App, _ int) ([]string, error)

func (NoopRuntime) Pull 

func (NoopRuntime) Pull(ctx context.Context, _ App) error

func (NoopRuntime) Restart 

func (NoopRuntime) Restart(ctx context.Context, _ App) error

func (NoopRuntime) Start 

func (NoopRuntime) Start(ctx context.Context, _ App) error

func (NoopRuntime) Status 

func (NoopRuntime) Status(ctx context.Context, app App) (AppStatus, error)

func (NoopRuntime) Stop 

func (NoopRuntime) Stop(ctx context.Context, _ App) error

func (NoopRuntime) Update 

func (NoopRuntime) Update(ctx context.Context, _ App) error

type Permissions 

type Permissions struct {
	Status  bool
	Logs    bool
	Start   bool
	Stop    bool
	Restart bool
	Pull    bool
	Update  bool
	Exec    bool
}

Permissions defines which container lifecycle operations are allowed.

type PortMapping 

type PortMapping struct {
	Host      string `json:"host,omitzero"`
	HostPort  string `json:"host_port,omitzero"`
	Container string `json:"container,omitzero"`
	Protocol  string `json:"protocol,omitzero"`
}

PortMapping represents a single host-to-container port binding.

type Registry 

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

Registry holds the current set of discovered homelab applications and their associated permissions, protected by a read-write mutex.

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Get 

func (r *Registry) Get(name string) (App, bool)

func (*Registry) List 

func (r *Registry) List() []App

func (*Registry) Permissions 

func (r *Registry) Permissions() Permissions

func (*Registry) Replace 

func (r *Registry) Replace(apps []App)

func (*Registry) SetPermissions 

func (r *Registry) SetPermissions(p Permissions)

type Runtime 

type Runtime interface {
	Status(ctx context.Context, app App) (AppStatus, error)
	Logs(ctx context.Context, app App, tail int) ([]string, error)
	Start(ctx context.Context, app App) error
	Stop(ctx context.Context, app App) error
	Restart(ctx context.Context, app App) error
	Pull(ctx context.Context, app App) error
	Update(ctx context.Context, app App) error
}

Runtime defines the container lifecycle operations that can be performed on a homelab application. 

var DefaultRuntime Runtime = NoopRuntime{}

DefaultRuntime is the process-wide runtime used when no explicit runtime is provided. Defaults to NoopRuntime.

func NewRuntime 

func NewRuntime(config RuntimeConfig, appsDir string) Runtime

NewRuntime selects the appropriate Runtime implementation based on the configured mode.

type RuntimeConfig 

type RuntimeConfig struct {
	Mode         RuntimeMode
	DockerSocket string
	SSHHost      string
	SSHPort      int
	SSHUser      string
	SSHPassword  string
	SSHKey       string
	SSHHostKey   string
}

RuntimeConfig selects the runtime mode and its connection parameters.

type RuntimeMode 

type RuntimeMode string

RuntimeMode selects which backend the homelab runtime uses. 

const (
	RuntimeModeNone         RuntimeMode = "none"
	RuntimeModeDockerSocket RuntimeMode = "docker_socket"
	RuntimeModeSSH          RuntimeMode = "ssh"
)

type SSHRuntime 

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

SSHRuntime executes docker compose commands on a remote host over SSH.

func NewSSHRuntime 

func NewSSHRuntime(config RuntimeConfig, appsDir string) *SSHRuntime

NewSSHRuntime creates an SSHRuntime that connects to the configured host.

func (*SSHRuntime) Logs 

func (r *SSHRuntime) Logs(ctx context.Context, app App, tail int) ([]string, error)

func (*SSHRuntime) Pull 

func (r *SSHRuntime) Pull(ctx context.Context, app App) error

func (*SSHRuntime) Restart 

func (r *SSHRuntime) Restart(ctx context.Context, app App) error

func (*SSHRuntime) Start 

func (r *SSHRuntime) Start(ctx context.Context, app App) error

func (*SSHRuntime) Status 

func (r *SSHRuntime) Status(ctx context.Context, app App) (AppStatus, error)

func (*SSHRuntime) Stop 

func (r *SSHRuntime) Stop(ctx context.Context, app App) error

func (*SSHRuntime) Update 

func (r *SSHRuntime) Update(ctx context.Context, app App) error

type Scanner 

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

Scanner discovers homelab applications by scanning a directory for Docker Compose files and parsing their metadata.

func NewScanner 

func NewScanner(config Config) *Scanner

NewScanner creates a Scanner with normalised configuration defaults.

func (*Scanner) Scan 

func (s *Scanner) Scan() ([]App, error)

Scan reads the configured apps directory and returns all discovered applications that have valid compose files and pass the allowlist filter.

Source Files

View all Source files

Directories

Path Synopsis
Package probe provides homelab service discovery and authentication detection.
 Package probe provides homelab service discovery and authentication detection.

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.