Help us shape the future of Go! Take the 2026 Go Developer Survey

compose

package
v1.4.5 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ProtocolHTTP proxies with Caddy's default upstream transport
	// (HTTP/1.1 to plaintext upstreams). This is the default.
	ProtocolHTTP = "http"
	// ProtocolH2C proxies with HTTP/2 cleartext (prior knowledge) to the upstream.
	ProtocolH2C = "h2c"
	// ProtocolGRPC is h2c to the upstream, matched only for native gRPC
	// requests (Content-Type application/grpc*, excluding gRPC-Web).
	ProtocolGRPC = "grpc"
)

Endpoint protocol values for simpledeploy.endpoints.N.protocol.

Variables

View Source 
var ErrDotEnv = errors.New("the app's .env file cannot be used")

ErrDotEnv marks an app .env file that cannot be used: a symlink, or a syntax error that docker compose would reject too.

Functions

func EffectiveTLS added in v1.4.0 

func EffectiveTLS(t string) string

EffectiveTLS normalizes an endpoint tls label for comparison: empty and "letsencrypt" mean the default "auto".

func EndpointMatchKey added in v1.4.0 

func EndpointMatchKey(ep EndpointConfig) string

EndpointMatchKey identifies the Caddy matcher an endpoint produces. Two endpoints with the same key would shadow each other. h2c and http differ only in upstream transport, so they share a key; grpc adds a Content-Type matcher, so it does not.

func EndpointRef added in v1.4.0 

func EndpointRef(ep EndpointConfig) string

EndpointRef names an endpoint by its label, e.g. `service "web" label simpledeploy.endpoints.2`.

func InjectSharedNetwork 

func InjectSharedNetwork(yamlContent []byte, networkName string) ([]byte, bool, error)

InjectSharedNetwork rewrites a compose YAML to declare the given shared external network and attach every service that has endpoint labels to it. Returns new bytes, whether any change was made, and an error.

func NormalizeProtocol added in v1.4.0 

func NormalizeProtocol(p string) string

NormalizeProtocol lowercases and trims a protocol label value.

func ReadDotEnv added in v1.4.3 

func ReadDotEnv(dir string) ([]byte, error)

ReadDotEnv returns the .env file in dir, or nil when there is none. A symlinked .env is refused so it cannot pull in a file from outside the app folder.

func SetAllowedHostPaths added in v1.4.3 

func SetAllowedHostPaths(paths []string)

SetAllowedHostPaths registers host folders the operator explicitly allows apps to bind-mount even though they sit under a protected system folder (config.yaml allowed_bind_paths, e.g. /home/media). SimpleDeploy's data folder and other apps' folders stay protected. Relative or empty entries are ignored.

func SetProtectedPaths added in v1.4.3 

func SetProtectedPaths(dataDir, appsDir string)

SetProtectedPaths registers SimpleDeploy's data folder and apps folder. Bind mounts may not reach the data folder (database, secrets, backups) and may only reach the apps folder inside the app's own folder. Empty values disable that rule.

func ValidPath added in v1.4.0 

func ValidPath(p string) bool

ValidPath reports whether p is an acceptable endpoint path matcher.

func ValidProtocol added in v1.4.0 

func ValidProtocol(p string) bool

ValidProtocol reports whether p (already normalized) is a supported endpoint protocol. Empty means the default (http).

func ValidateComposeForDeploy added in v1.4.0 

func ValidateComposeForDeploy(cfg *AppConfig) []string

ValidateComposeForDeploy is ValidateComposeSecurity plus endpoint label validation (ValidateEndpoints). Used by paths that accept new compose files (deploy API, bundle import) so bad routing labels are rejected up front. The reconciler disk scan only warns on endpoint problems, so an existing app is never dropped from routing after an upgrade.

func ValidateComposeSecurity 

func ValidateComposeSecurity(cfg *AppConfig) []string

ValidateComposeSecurity checks a parsed compose project for dangerous directives. Returns a list of violations. Empty list means safe.

func ValidateEndpoints added in v1.4.0 

func ValidateEndpoints(eps []EndpointConfig) []string

ValidateEndpoints checks protocol/path label values, rejects endpoints whose matchers collide and endpoints sharing a domain with different tls modes. Returns human-readable violations; empty = valid.

Types

type AppConfig 

type AppConfig struct {
	Name            string
	ComposePath     string
	Endpoints       []EndpointConfig
	BackupStrategy  string
	BackupSchedule  string
	BackupTarget    string
	BackupRetention string
	AlertCPU        string
	AlertMemory     string
	Registries      string
	AccessAllow     string
	RateLimit       RateLimitLabels
	Services        []ServiceConfig
	Project         *types.Project
	// contains filtered or unexported fields
}

AppConfig holds the parsed compose file config plus extracted simpledeploy labels.

func ParseContent added in v1.4.3 

func ParseContent(content []byte, path, appName string, dotEnv []byte) (*AppConfig, error)

ParseContent parses compose content as if it were stored at path, with dotEnv as the content of the .env file next to it (nil for none). This lets callers validate a compose file before it is written to disk.

It mirrors what `docker compose -f path` sees: relative paths resolve against the folder of path, and ${VAR} references are interpolated from dotEnv overridden by the process environment (docker compose inherits our environment). Without this, a value set in .env could hide a dangerous setting from the validator.

A top-level include, or a label_file or extends file that is not a regular file inside the app folder, returns a *ViolationError.

func ParseFile 

func ParseFile(path, appName string) (*AppConfig, error)

ParseFile parses the compose file at path and returns an AppConfig with appName as the name. simpledeploy.* labels are collected across all services; the first value found wins. ${VAR} references are interpolated the way `docker compose` does it (see ParseContent). A docker-compose.yml or .env that is a symlink is refused.

func ParseForRoutes added in v1.4.3 

func ParseForRoutes(path, appName string) (*AppConfig, error)

ParseForRoutes parses the compose file at path for routing only, for a file ParseFile refuses over its file references (*ViolationError). It drops a top-level include and each service's label_file and file-based extends, and ignores the app's .env. The result must never be deployed: it only keeps the routes of an unchanged running app known.

func (*AppConfig) PrimaryDomain 

func (a *AppConfig) PrimaryDomain() string

PrimaryDomain returns the domain of the first endpoint, or empty string.

type EndpointConfig 

type EndpointConfig struct {
	Domain   string `json:"domain"`
	Port     string `json:"port"`
	TLS      string `json:"tls"`
	Service  string `json:"service"`
	Protocol string `json:"protocol,omitempty"` // "", "http", "h2c" or "grpc"
	Path     string `json:"path,omitempty"`     // optional Caddy path matcher, e.g. "/ws*"
	// Index is N from the simpledeploy.endpoints.N.* labels (per service).
	// Used for deterministic ordering and error messages; not serialized.
	Index int `json:"-"`
}

EndpointConfig holds config for a single endpoint (domain/port/tls bound to a service).

type LabelConfig 

type LabelConfig struct {
	BackupStrategy  string
	BackupSchedule  string
	BackupTarget    string
	BackupRetention string
	AlertCPU        string
	AlertMemory     string
	Registries      string
	AccessAllow     string
	RateLimit       RateLimitLabels
}

LabelConfig holds all extracted simpledeploy.* labels (non-endpoint labels).

func ExtractLabels 

func ExtractLabels(labels map[string]string) LabelConfig

ExtractLabels extracts non-endpoint simpledeploy.* labels from the provided map.

type PortMapping 

type PortMapping struct {
	Host, Container, Protocol string
}

PortMapping represents a host:container port binding.

type RateLimitLabels 

type RateLimitLabels struct {
	Requests, Window, By, Burst string
}

RateLimitLabels holds simpledeploy.ratelimit.* label values.

type ServiceConfig 

type ServiceConfig struct {
	Name        string
	Image       string
	Ports       []PortMapping
	Environment map[string]string
	Volumes     []VolumeMount
	Restart     string
	Labels      map[string]string
	DependsOn   []string
	DeployMode  string
}

ServiceConfig is a simplified representation of a compose service.

func (*ServiceConfig) ScaleEligibility 

func (s *ServiceConfig) ScaleEligibility() (bool, string)

ScaleEligibility reports whether the service can safely run with N>1 replicas. Returns (true, "") when scalable, (false, reason) otherwise.

Detection rules (in order):

  1. simpledeploy.scalable=false label forces non-scalable.
  2. simpledeploy.scalable=true label forces scalable (override).
  3. deploy.mode: global (one container per node).
  4. Any host-published port (would clash on the same host).
  5. Named volumes (typically stateful).
  6. Known stateful image (database, broker, etc.).

type ViolationError added in v1.4.3 

type ViolationError struct {
	Violations []string
}

ViolationError reports a compose file refused by ValidateComposeSecurity.

func (*ViolationError) Error added in v1.4.3 

func (e *ViolationError) Error() string

type VolumeMount 

type VolumeMount struct {
	Source, Target, Type string
}

VolumeMount represents a service volume mount.

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.