engine

Documentation

Index

• Constants
• func AttachMiddleware(labels map[string]string, service string, middlewareName string) map[string]string
• func GenerateLabels(input RouteInput) map[string]string
• func GenerateMiddlewareLabels(input MiddlewareInput) map[string]string
• func InjectLabels(composePath string, service string, labels map[string]string) error
• type ComposeFile
  • func ParseCompose(path string) (*ComposeFile, error)
  • func ParseComposeBytes(data []byte) (*ComposeFile, error)
  • func (c *ComposeFile) GetContainerPort(service string) int
  • func (c *ComposeFile) GetExposedPorts(service string) []int
  • func (c *ComposeFile) GetTraefikLabels(service string) map[string]string
  • func (c *ComposeFile) ServiceNames() []string
• type DeployResult
  • func DeployStack(composePath string, timeout time.Duration) (*DeployResult, error)
  • func PullStack(composePath string, timeout time.Duration) (*DeployResult, error)
  • func StopStack(composePath string, timeout time.Duration) (*DeployResult, error)
  • func ValidateAndDeploy(composePath string, routes []RouteInput, timeout time.Duration) (*DeployResult, error)
• type MiddlewareInput
• type RouteInput
• type Service
• type ValidationError
  • func ValidateCompose(cf *ComposeFile) []ValidationError
  • func ValidateDomain(domain string) []ValidationError
  • func ValidateDomainUnique(domain string, existing []RouteInput) []ValidationError
  • func ValidatePort(port int) []ValidationError
  • func ValidatePortAvailable(port int) *ValidationError
  • func ValidateRoute(r RouteInput) []ValidationError
  • func (e ValidationError) Error() string

Constants

const DefaultTimeout = 120 * time.Second

DefaultTimeout for deployments.

Functions

func AttachMiddleware

func AttachMiddleware(labels map[string]string, service string, middlewareName string) map[string]string

AttachMiddleware links a middleware to an existing router in labels. It appends the middleware name to the router's middlewares list.

func GenerateLabels

func GenerateLabels(input RouteInput) map[string]string

GenerateLabels produces the standard set of Traefik Docker labels for a given route input. This is the core differentiator — one clean opinionated way to route a service.

func GenerateMiddlewareLabels

func GenerateMiddlewareLabels(input MiddlewareInput) map[string]string

GenerateMiddlewareLabels produces Traefik middleware labels based on type.

Supported types:

• "basicauth": requires "users" in config (htpasswd format)
• "ratelimit": requires "average" and optionally "burst"
• "stripprefix": requires "prefixes" (comma-separated)
• "headers": supports "stsSeconds", "browserXssFilter", etc.

func InjectLabels

func InjectLabels(composePath string, service string, labels map[string]string) error

InjectLabels reads a compose file, merges the given labels into the specified service's label block, and writes the result back to disk. Existing labels with the same key are overwritten.

Types

type ComposeFile

type ComposeFile struct {
	Services map[string]Service `yaml:"services"`
	Networks map[string]any     `yaml:"networks,omitempty"`
	Volumes  map[string]any     `yaml:"volumes,omitempty"`
}

ComposeFile represents a parsed docker-compose.yml

func ParseCompose

func ParseCompose(path string) (*ComposeFile, error)

ParseCompose reads and parses a docker-compose.yml file.

func ParseComposeBytes

func ParseComposeBytes(data []byte) (*ComposeFile, error)

ParseComposeBytes parses compose YAML from raw bytes.

func (*ComposeFile) GetContainerPort

func (c *ComposeFile) GetContainerPort(service string) int

GetContainerPort extracts the internal container port from the first port mapping. Returns 0 if no ports are defined.

func (*ComposeFile) GetExposedPorts

func (c *ComposeFile) GetExposedPorts(service string) []int

GetExposedPorts extracts host-side ports from a service's port mappings. It handles formats: "8080", "8080:80", "127.0.0.1:8080:80".

func (*ComposeFile) GetTraefikLabels

func (c *ComposeFile) GetTraefikLabels(service string) map[string]string

GetTraefikLabels extracts existing Traefik labels from a service. Returns nil if the service does not exist.

func (*ComposeFile) ServiceNames

func (c *ComposeFile) ServiceNames() []string

ServiceNames returns a sorted list of service names.

type DeployResult

type DeployResult struct {
	Stack    string        `json:"stack"`
	Status   string        `json:"status"` // "success", "failed", "timeout"
	Duration time.Duration `json:"duration"`
	Logs     string        `json:"logs,omitempty"`
}

DeployResult captures the outcome of a stack deployment.

func DeployStack

func DeployStack(composePath string, timeout time.Duration) (*DeployResult, error)

DeployStack runs `docker compose up -d` on a compose file with safety.

• Context-based timeout (default 120s)
• Captured stdout/stderr
• Structured result

func PullStack

func PullStack(composePath string, timeout time.Duration) (*DeployResult, error)

PullStack runs `docker compose pull` on a compose file.

func StopStack

func StopStack(composePath string, timeout time.Duration) (*DeployResult, error)

StopStack runs `docker compose down` on a compose file.

func ValidateAndDeploy

func ValidateAndDeploy(composePath string, routes []RouteInput, timeout time.Duration) (*DeployResult, error)

ValidateAndDeploy runs validation before deployment. If validation fails, deployment is aborted.

type MiddlewareInput

type MiddlewareInput struct {
	Name   string            `json:"name"`
	Type   string            `json:"type"`   // "basicauth", "ratelimit", "stripprefix", "headers"
	Config map[string]string `json:"config"` // type-specific key/value pairs
}

MiddlewareInput describes a Traefik middleware configuration.

type RouteInput

type RouteInput struct {
	Service     string `json:"service"`
	Domain      string `json:"domain"`
	Port        int    `json:"port"`
	Entrypoints string `json:"entrypoints,omitempty"` // default: "web"
	Network     string `json:"network,omitempty"`     // default: "proxy"
}

RouteInput is the core input for generating Traefik labels.

type Service

type Service struct {
	Image         string      `yaml:"image"`
	Ports         []string    `yaml:"ports,omitempty"`
	Labels        yamlLabels  `yaml:"labels,omitempty"`
	Environment   yamlEnvList `yaml:"environment,omitempty"`
	Networks      yamlList    `yaml:"networks,omitempty"`
	VolumesRaw    []string    `yaml:"volumes,omitempty"`
	EnvFile       yamlList    `yaml:"env_file,omitempty"`
	ContainerName string      `yaml:"container_name,omitempty"`
	Restart       string      `yaml:"restart,omitempty"`
	Command       string      `yaml:"command,omitempty"`
}

Service represents a single service in a compose file

type ValidationError

type ValidationError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

ValidationError describes a single validation failure.

func ValidateCompose

func ValidateCompose(cf *ComposeFile) []ValidationError

ValidateCompose checks a parsed compose file for common issues.

func ValidateDomain

func ValidateDomain(domain string) []ValidationError

ValidateDomain checks that a domain string is well-formed.

func ValidateDomainUnique

func ValidateDomainUnique(domain string, existing []RouteInput) []ValidationError

ValidateDomainUnique checks that a domain is not already in use.

func ValidatePort

func ValidatePort(port int) []ValidationError

ValidatePort checks that a port number is valid and not reserved.

func ValidatePortAvailable

func ValidatePortAvailable(port int) *ValidationError

ValidatePortAvailable checks if a port is currently in use on the host.

func ValidateRoute

func ValidateRoute(r RouteInput) []ValidationError

ValidateRoute checks a RouteInput for correctness.

func (ValidationError) Error

func (e ValidationError) Error() string