Documentation
¶
Overview ¶
Package config provides Docker container label parsing for roji configuration.
It extracts routing configuration from Docker labels such as:
- roji.host: Custom hostname
- roji.port: Target port
- roji.path: Path prefix for path-based routing
Index ¶
- Constants
- func CertsDir() string
- func ConfigDir() string
- func ConfigFilePath() string
- func DataDir() string
- func DefaultHostname(serviceName, baseDomain string) string
- func EnsureDir(path string) error
- func Exists(path string) bool
- func ExpandPath(path string) string
- func IsLoopbackAddr(addr string) bool
- func IsWildcardAddr(addr string) bool
- func LogFilePath() string
- type BasicAuth
- type MockRoute
- type Paths
- type RouteConfig
- type Settings
- type StaticSite
- type StaticSiteAuth
- type ValidationIssue
- type ValidationResult
Constants ¶
const ( // Label prefix for all roji-related labels LabelPrefix = "roji." // Supported labels LabelHost = LabelPrefix + "host" // Custom hostname (default: {service}.{domain}) LabelPort = LabelPrefix + "port" // Target port when multiple ports exposed LabelPath = LabelPrefix + "path" // Path prefix for routing (optional) // Mock labels prefix LabelMockPrefix = LabelPrefix + "mock." // roji.mock.GET./path = response body LabelMockStatusPrefix = LabelMockPrefix + "status." // roji.mock.status.GET./path = status code // Basic auth labels LabelAuthBasicUser = LabelPrefix + "auth.basic.user" // Basic auth username LabelAuthBasicPass = LabelPrefix + "auth.basic.pass" // Basic auth password LabelAuthBasicRealm = LabelPrefix + "auth.basic.realm" // Basic auth realm (optional) )
const (
// AppName is the application name used for directory paths
AppName = "roji"
)
const DefaultBind = "127.0.0.1,::1"
DefaultBind is the address set roji listens on when nothing else is configured: both loopback addresses, and nothing beyond the machine itself.
Both are needed because the wildcard listener this replaced accepted IPv4 and IPv6 alike, and a browser resolving a *.localhost name may pick either.
Variables ¶
This section is empty.
Functions ¶
func CertsDir ¶ added in v0.8.0
func CertsDir() string
CertsDir returns the certificates directory Defaults to DataDir()/certs
func ConfigDir ¶ added in v0.8.0
func ConfigDir() string
ConfigDir returns the configuration directory following XDG spec Linux/macOS: ~/.config/roji Windows: %APPDATA%\roji
func ConfigFilePath ¶ added in v0.8.0
func ConfigFilePath() string
ConfigFilePath returns the path to the configuration file
func DataDir ¶ added in v0.8.0
func DataDir() string
DataDir returns the data directory following XDG spec Linux/macOS: ~/.local/share/roji Windows: %LOCALAPPDATA%\roji
func DefaultHostname ¶
DefaultHostname generates a default hostname from service name and base domain e.g., ("myapp", "kan.localhost") -> "myapp.kan.localhost"
func ExpandPath ¶ added in v0.9.0
ExpandPath expands ~ to home directory
func IsLoopbackAddr ¶ added in v1.1.0
IsLoopbackAddr reports whether addr names the machine roji runs on and nothing else.
A hostname is not judged here: deciding what it points at means resolving it, which belongs to whoever is about to connect or listen. The wildcard is not loopback either, since it accepts connections from anywhere.
func IsWildcardAddr ¶ added in v1.1.0
IsWildcardAddr reports whether addr is the wildcard. The bind setting spells it as the empty string, which net.JoinHostPort turns into ":443" — the address that accepts connections on every interface.
func LogFilePath ¶ added in v0.9.0
func LogFilePath() string
LogFilePath returns the path to the log file
Types ¶
type BasicAuth ¶ added in v0.9.0
type BasicAuth struct {
User string // Username
Pass string // Password
Realm string // Authentication realm (optional, default: "Restricted")
}
BasicAuth holds basic authentication credentials
type MockRoute ¶ added in v0.6.0
type MockRoute struct {
Method string // HTTP method (GET, POST, etc.)
Path string // URL path (e.g., "/api/users")
Body string // Response body
StatusCode int // HTTP status code (default: 200)
}
MockRoute defines a mock response for a specific method and path
type Paths ¶ added in v0.8.0
type Paths struct {
ConfigDir string // Directory for configuration files
DataDir string // Directory for data files (projects.json, etc.)
CertsDir string // Directory for certificates
}
Paths holds the resolved paths for configuration and data directories
func DefaultPaths ¶ added in v0.8.0
func DefaultPaths() *Paths
DefaultPaths returns the default paths following XDG Base Directory specification
type RouteConfig ¶
type RouteConfig struct {
Host string // e.g., "myapp.localhost"
Port int // Target port
// PathPrefix is empty, or a rooted path with no trailing slash ("/api").
// Empty is the only spelling of "no prefix": a label naming the root gives
// an empty prefix rather than "/".
PathPrefix string
MockRoutes []*MockRoute // Mock responses for this container
BasicAuth *BasicAuth // Basic authentication (optional)
}
RouteConfig holds the configuration for a single route
func ParseLabels ¶
func ParseLabels(labels map[string]string) *RouteConfig
ParseLabels extracts roji configuration from container labels
type Settings ¶ added in v0.8.0
type Settings struct {
Network string `yaml:"network"` // Docker network name(s) (comma-separated)
Domain string `yaml:"domain"` // Base domain (e.g., dev.localhost)
Bind string `yaml:"bind"` // Listen address(es) (comma-separated); empty means all interfaces
HTTPPort int `yaml:"http_port"` // HTTP port (for redirect)
HTTPSPort int `yaml:"https_port"` // HTTPS port
CertsDir string `yaml:"certs_dir"` // Directory for TLS certificates
DataDir string `yaml:"data_dir"` // Directory for persistent data
Dashboard string `yaml:"dashboard"` // Dashboard hostname
LogLevel string `yaml:"log_level"` // Log level (debug, info, warn, error)
AutoCert bool `yaml:"auto_cert"` // Auto-generate certificates
StaticSites []StaticSite `yaml:"static_sites,omitempty"` // Static file hosting sites
}
Settings holds all configuration settings for roji
func Defaults ¶ added in v0.8.0
func Defaults() *Settings
Defaults returns settings with default values
func Load ¶ added in v0.8.0
Load loads configuration with the following priority (highest to lowest): 1. CLI overrides (passed in cliOverrides) 2. Environment variables (ROJI_*) 3. Config file 4. Defaults
func (*Settings) BindAddrs ¶ added in v1.1.0
BindAddrs returns the addresses to listen on, one per listener.
An empty setting means every interface, returned as a single wildcard entry; it is the only case where the list holds one, since parsing drops empty parts.
func (*Settings) ListensBeyondLoopback ¶ added in v1.1.0
ListensBeyondLoopback reports whether any listener accepts connections from outside the machine. That matters because roji publishes every container on its network without requiring a label, and the dashboard's Compose endpoints have no authentication: reaching roji is enough to control containers.
func (*Settings) LocalAddr ¶ added in v1.1.0
LocalAddr returns an address this machine can reach the server on.
Loopback is preferred because a connection to it never leaves the machine. The wildcard has no address of its own, so localhost stands in. Otherwise any configured address will do: the server bound it, so it names an interface here. Order within the setting is not meaningful, so nothing depends on it beyond that last case, where every candidate is equivalent.
func (*Settings) SaveToFile ¶ added in v0.8.0
SaveToFile saves settings to a YAML file
type StaticSite ¶ added in v0.9.0
type StaticSite struct {
Host string `yaml:"host"` // Hostname or subdomain (e.g., "docs" or "docs.example.com")
Root string `yaml:"root"` // Root directory path (supports ~ expansion)
Index *bool `yaml:"index,omitempty"` // Enable directory listing (default: true, set false to disable)
Auth *StaticSiteAuth `yaml:"auth,omitempty"` // Authentication configuration
}
StaticSite represents a static file hosting configuration
func (*StaticSite) GetBasicAuth ¶ added in v0.9.0
func (s *StaticSite) GetBasicAuth() *BasicAuth
GetBasicAuth returns the basic auth configuration if set
func (*StaticSite) IndexEnabled ¶ added in v0.9.0
func (s *StaticSite) IndexEnabled() bool
IndexEnabled returns whether directory listing is enabled (default: true)
type StaticSiteAuth ¶ added in v0.9.0
type StaticSiteAuth struct {
Basic *BasicAuth `yaml:"basic,omitempty"` // Basic authentication
}
StaticSiteAuth holds authentication configuration for a static site
type ValidationIssue ¶ added in v0.9.0
type ValidationIssue struct {
Path string // YAML path (e.g., "static_sites[0].auth.basic")
Type string // Issue type: "unknown_key", "invalid_type"
Message string // Human-readable message
}
ValidationIssue represents a single validation issue
type ValidationResult ¶ added in v0.9.0
type ValidationResult struct {
Issues []ValidationIssue
}
ValidationResult holds the result of config validation
func ValidateConfigYAML ¶ added in v0.9.0
func ValidateConfigYAML(data []byte) *ValidationResult
ValidateConfigYAML validates raw YAML config data
func (*ValidationResult) FormatMessages ¶ added in v0.9.0
func (r *ValidationResult) FormatMessages() []string
FormatMessages returns all issues as formatted strings
func (*ValidationResult) HasIssues ¶ added in v0.9.0
func (r *ValidationResult) HasIssues() bool
HasIssues returns true if any validation issues were found
func (*ValidationResult) LogWarnings ¶ added in v0.9.0
func (r *ValidationResult) LogWarnings()
LogWarnings logs all validation issues as warnings