Documentation
¶
Overview ¶
Package config loads runtime configuration from flags and environment variables and resolves sensible cross-platform defaults.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NormalizePathPrefix ¶ added in v1.7.2
NormalizePathPrefix turns a URL path prefix ("/dockercmd/", "dockercmd") into its canonical form ("/dockercmd"); "" and "/" mean the root and return "". Only plain segments of unreserved characters (RFC 3986: letters, digits and -._~) are accepted, and "." / ".." are not segments. The result is written into HTML, cookies and redirects, and this is what keeps that safe: there is nothing in it to escape, and it can't start with "//" (a scheme-relative URL pointing at another host).
func PublicURLPath ¶ added in v1.7.2
PublicURLPath returns the path of a public base URL (DC_MCP_PUBLIC_URL) in the canonical form of NormalizePathPrefix: "" for https://host, "/dockercmd" for https://host/dockercmd/. The URL is the OAuth issuer, so it needs an http(s) scheme and a host: "docker.example.com" would otherwise parse as a path. The path becomes a route pattern, so it must be a plain prefix too; a query or fragment has no place in a base URL.
func ResolveDataDir ¶ added in v1.5.0
func ResolveDataDir() string
ResolveDataDir returns the data directory for standalone CLI actions, which run before Load parses flags: DC_DATA_DIR if set, else the OS default. The `-data-dir` flag is only honoured in server mode.
Types ¶
type Config ¶
type Config struct {
// Addr is the listen address. Defaults to loopback only; binding to a
// public interface is an explicit, conscious choice by the operator.
Addr string
// DataDir holds the SQLite database and any persisted secrets.
DataDir string
// SessionTTL is how long a logged-in session token stays valid.
SessionTTL time.Duration
// Dev enables developer conveniences (e.g. permissive CORS for Vite).
Dev bool
// UpdateCheck enables the periodic GitHub-release update check that backs
// the admin "update available" banner. On by default; set DC_UPDATE_CHECK=0
// (or -update-check=false) to disable outbound calls on air-gapped hosts.
UpdateCheck bool
// SelfUpdate allows an admin to download and apply an update from the web UI
// (the one-tap "Update & restart"). On by default; set DC_SELF_UPDATE=0 to
// keep the "update available" banner but forbid web-triggered self-replacement
// of the binary (e.g. when updates are managed by your packaging/orchestrator).
SelfUpdate bool
// MetricsToken, when set, requires a bearer token to scrape /metrics.
// Empty means the endpoint is open (fine for loopback-only use).
MetricsToken string
// TLSCert/TLSKey are paths to a PEM certificate and key. When both are set,
// the server speaks HTTPS directly (otherwise plain HTTP behind a proxy).
TLSCert string
TLSKey string
// ACMEDomains, when non-empty, enables automatic HTTPS: a certificate is
// obtained and renewed via ACME (Let's Encrypt by default) for these public
// hostnames instead of a static TLSCert/TLSKey pair — mutually exclusive
// with them. For a host sitting directly on the public internet with no
// reverse proxy in front (the proxy case already terminates TLS itself).
ACMEDomains []string
// ACMEEmail is optionally registered with the ACME account, so the CA can
// reach the operator about renewal problems or policy changes. Not required.
ACMEEmail string
// ACMECacheDir persists the obtained certificate/key and ACME account state
// between restarts, so a restart doesn't re-issue a certificate and burn
// into the CA's rate limits. Defaults to <data-dir>/acme.
ACMECacheDir string
// ACMEDirectoryURL overrides the ACME server (default: Let's Encrypt
// production) — e.g. Let's Encrypt's staging directory, to test without
// spending production rate-limit budget or minting a real cert, or an
// entirely different ACME-compliant CA. NOT a local Pebble instance for
// exercising this server's own obtain-and-serve path: Pebble's directory
// endpoint uses a locally-generated, untrusted TLS cert (so this process
// refuses to talk to it, correctly, the same as it would refuse any
// other unverifiable server), and separately, its order-polling response
// shape trips a gap in autocert's client library. See docs/gotchas.md.
// Pebble is still useful for developing this package itself — see
// internal/acme/pebble_integration_test.go, which works around both by
// driving the ACME protocol at a lower level than this server does.
ACMEDirectoryURL string
// MCPEnabled turns on the remote MCP server (and its OAuth endpoints). Off by
// default: when false the /mcp, /oauth and MCP /.well-known routes are not
// mounted, so a request is an unknown path (it falls through to the SPA, or a
// 404 without an embedded UI) — no hint the feature exists. It exposes Docker
// read/control to AI tooling over the network — enable consciously, behind
// HTTPS. Startup logs the resolved on/off state.
MCPEnabled bool
// MCPPublicURL is the externally reachable base URL of this server
// (e.g. https://docker.example.com, or https://example.com/dockercmd under
// a path), used as the canonical resource
// identifier for OAuth audience binding and the protected-resource metadata.
// Empty is fine for Bearer-only (Claude Code header) use; the OAuth flow
// needs it set.
MCPPublicURL string
// ProxyEnabled turns on the embedded per-container reverse proxy: routing
// public traffic for a project's domain_mappings entries to that
// project's actual running container, over the SAME shared listener as
// DC's own admin UI (SNI-dispatched). Off by default — this opens a
// second public attack surface distinct from DC's own admin UI/API, so
// it must be a conscious opt-in. Only takes effect when ACME mode is
// also active for DC's own admin domain(s) (len(ACMEDomains) > 0); if
// ProxyEnabled is true without ACME mode, startup logs a clear no-op
// message rather than failing. Local-host projects only in this phase —
// see NEXT.md's "Reverse proxy and ingress".
ProxyEnabled bool
// ProxyACMECacheDir persists the proxy's OWN obtained certificates and
// ACME account state, kept in a directory separate from ACMECacheDir (DC's
// own admin-domain cache) — a compromise of one manager's cache must not
// expose the other's account key. Defaults to <data-dir>/proxy-acme.
ProxyACMECacheDir string
// Version is the build version string, set by main (not from flags/env).
Version string
// ConfigFile is the config file that was loaded, or "" if none.
ConfigFile string
// Warnings are config-file problems that don't stop the server (a key it
// never reads, a line that isn't KEY=VALUE). main logs them at startup.
Warnings []string
// Metrics history backend. RedisAddr empty → in-memory ring buffer.
RedisAddr string
RedisPassword string
RedisDB int
MetricsRetention time.Duration
// MetricsInterval is how often the monitor samples every running container's
// stats (feeding the charts/history and resource alert rules). Lower means
// fresher data but more CPU on the app and the Docker daemon; raise it on a
// host with many containers where the sweep is costly.
MetricsInterval time.Duration
// PProf exposes Go's net/http/pprof profiling endpoints under /debug/pprof.
// Off by default; when on, the endpoints are restricted to loopback clients
// (use an SSH tunnel) since they leak goroutine stacks and heap detail.
PProf bool
// LogFile, when set, is where the log goes instead of stderr, rotated at
// 10 MiB with one older copy. For a process nothing captures stderr from:
// a Windows Scheduled Task, or a detached run.
LogFile string
// DeploySilenceGrace is how long alert delivery is automatically silenced
// for a project immediately after a successful deploy — containers
// restarting, warming up or briefly reporting a stale health check are
// expected noise, not an incident. 0 disables the automatic silence
// entirely (unlike MetricsInterval, 0 here is a valid, deliberate choice,
// not clamped to a default).
DeploySilenceGrace time.Duration
// TrustedProxies is the set of reverse-proxy networks whose forwarded client
// IP (X-Forwarded-For) we trust. Empty (default) means forwarded headers are
// IGNORED and the real TCP peer is used for every IP-based decision (rate
// limits, the loopback 2FA exemption, audit) — so a remote client cannot
// spoof its address. Set it (e.g. 127.0.0.1/32,::1/128) only for the actual
// proxy in front of this server.
TrustedProxies []*net.IPNet
// BasePath is the URL path prefix the UI and API are published under when
// the reverse proxy in front does not say so itself (e.g. "/dockercmd" for
// https://example.com/dockercmd/). Normalised: leading slash, no trailing
// one; "" means the root. Requests may arrive with or without it.
BasePath string
// ForwardedPrefix makes an X-Forwarded-Prefix request header override
// BasePath for that request. On by default (DC_FORWARDED_PREFIX=0 turns it
// off). The header is believed from any peer, but only a value made of
// plain path segments is accepted, so it can't inject markup or redirect
// off-site; at worst a client changes the links in its own response.
ForwardedPrefix bool
}
Config holds all runtime options.
func Load ¶
Load parses flags/env/config-file and returns the resolved configuration.
Precedence (highest first): command-line flag → environment variable → config file → built-in default. The config file is a simple "KEY=VALUE" file using the same DC_* keys as the environment. Its path comes from -config, then $DC_CONFIG, then the platform default (/etc/docker-commander/ commander.conf on Unix, %ProgramData%\docker-commander\commander.conf on Windows); a missing default file is ignored, a missing explicit one errors.
func (Config) TLSEnabled ¶ added in v1.7.0
TLSEnabled reports whether the server should speak HTTPS — either from a static cert/key pair or from ACME-obtained domains. The two are mutually exclusive (enforced in Load), so this is never true from both at once.