config

package
v0.84.0 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const AppName = "doco-cd" // Name of the application
View Source 
const DefaultReference = "refs/heads/main"
View Source 
const MinPollInterval = 10 // Minimum allowed poll interval in seconds

Variables

View Source 
var (
	DefaultDeploymentConfigFileNames = []string{".doco-cd.yaml", ".doco-cd.yml"}
	CustomDeploymentConfigFileNames  = []string{".doco-cd.%s.yaml", ".doco-cd.%s.yml"}
	ErrConfigFileNotFound            = errors.New("configuration file not found in repository")
	ErrDuplicateProjectName          = errors.New("duplicate project/stack name found in configuration file")
	ErrInvalidConfig                 = errors.New("invalid deploy configuration")
	ErrKeyNotFound                   = errors.New("key not found")
	ErrInvalidFilePath               = errors.New("invalid file path")
)
View Source 
var (
	ErrInvalidLogLevel   = validator.TextErr{Err: errors.New("invalid log level, must be one of debug, info, warn, error")}
	ErrBothSecretsSet    = errors.New("both secrets are set, please use one or the other")
	ErrBothSecretsNotSet = errors.New("neither secrets are set, please use one or the other")
	ErrInvalidHttpUrl    = errors.New("invalid HTTP URL")
	ErrParseConfigFailed = errors.New("failed to parse config from environment")
)
View Source 
var (
	ErrInvalidPollConfig  = errors.New("invalid poll configuration")
	ErrBothPollConfigSet  = errors.New("both POLL_CONFIG and POLL_CONFIG_FILE are set, please use one or the other")
	ErrPollIntervalTooLow = errors.New("poll interval too low")
)
View Source 
var AppVersion = "dev" // Version of the application, to be set during build time

Functions

func EncodeExternalSecretRefs added in v0.80.0 

func EncodeExternalSecretRefs(in map[string]ExternalSecretRef) (map[string]string, error)

EncodeExternalSecretRefs converts typed references to provider input values.

func LoadFileBasedEnvVars added in v0.36.0 

func LoadFileBasedEnvVars(mappings *[]EnvVarFileMapping) error

LoadFileBasedEnvVars loads env-based config values from file-based env vars if set.

func LoadLocalDotEnv added in v0.50.0 

func LoadLocalDotEnv(deployConfig *DeployConfig, basePath string) error

LoadLocalDotEnv processes local dotenv files and loads their variables into the DeployConfig.Internal.Environment map. Remote dotenv files (prefixed with "remote:") are collected and left in DeployConfig.EnvFiles for later processing.

func ParseConfigFromEnv added in v0.36.0 

func ParseConfigFromEnv(config any, mappings *[]EnvVarFileMapping) error

ParseConfigFromEnv parses the configuration from environment variables and file-based environment variables.

Types

type AppConfig 

type AppConfig struct {
	LogLevel                    string                 `env:"LOG_LEVEL,notEmpty" envDefault:"info"`                          // LogLevel is the log level for the application
	HttpPort                    uint16                 `env:"HTTP_PORT,notEmpty" envDefault:"80" validate:"min=1,max=65535"` // HttpPort is the port the HTTP server will listen on
	HttpProxyString             string                 `env:"HTTP_PROXY"`                                                    // HttpProxyString is the HTTP proxy URL as a string
	HttpProxy                   transport.ProxyOptions // HttpProxy is the HTTP proxy configuration parsed from the HttpProxyString
	ApiSecret                   string                 `env:"API_SECRET"`                                                          // #nosec G117 -- ApiSecret is the secret token used to authenticate with the API
	ApiSecretFile               string                 `env:"API_SECRET_FILE,file"`                                                // ApiSecretFile is the file containing the ApiSecret
	WebhookSecret               string                 `env:"WEBHOOK_SECRET"`                                                      // WebhookSecret is the secret token used to authenticate the webhook
	WebhookSecretFile           string                 `env:"WEBHOOK_SECRET_FILE,file"`                                            // WebhookSecretFile is the file containing the WebhookSecret
	GitAccessToken              string                 `env:"GIT_ACCESS_TOKEN"`                                                    // GitAccessToken is the access token used to authenticate with the Git server (e.g. GitHub) for private repositories
	GitAccessTokenFile          string                 `env:"GIT_ACCESS_TOKEN_FILE,file"`                                          // GitAccessTokenFile is the file containing the GitAccessToken
	GitCloneDepth               int                    `env:"GIT_CLONE_DEPTH,notEmpty" envDefault:"0" validate:"min=0"`            // GitCloneDepth limits the number of commits to fetch. 0 means full clone (no depth limit). A positive value enables shallow clones.
	GitCloneSubmodules          bool                   `env:"GIT_CLONE_SUBMODULES,notEmpty" envDefault:"true"`                     // GitCloneSubmodules controls whether git submodules are cloned
	SSHPrivateKey               string                 `env:"SSH_PRIVATE_KEY"`                                                     // SSHPrivateKey is the SSH private key used for SSH authentication with Git repositories
	SSHPrivateKeyFile           string                 `env:"SSH_PRIVATE_KEY_FILE,file"`                                           // SSHPrivateKeyFile is the file containing the SSHPrivateKey
	SSHPrivateKeyPassphrase     string                 `env:"SSH_PRIVATE_KEY_PASSPHRASE"`                                          // SSHPrivateKeyPassphrase is the passphrase for the SSH private key, if applicable
	SSHPrivateKeyPassphraseFile string                 `env:"SSH_PRIVATE_KEY_PASSPHRASE_FILE,file"`                                // SSHPrivateKeyPassphraseFile is the file containing the SSHPrivateKeyPassphrase
	AuthType                    string                 `env:"AUTH_TYPE,notEmpty" envDefault:"oauth2"`                              // AuthType is the type of authentication to use when cloning repositories
	SkipTLSVerification         bool                   `env:"SKIP_TLS_VERIFICATION,notEmpty" envDefault:"false"`                   // SkipTLSVerification skips the TLS verification when cloning repositories.
	DockerQuietDeploy           bool                   `env:"DOCKER_QUIET_DEPLOY,notEmpty" envDefault:"true"`                      // DockerQuietDeploy suppresses the status output of dockerCli in deployments (e.g. pull, create, start)
	DockerSwarmFeatures         bool                   `env:"DOCKER_SWARM_FEATURES,notEmpty" envDefault:"true"`                    // DockerSwarmFeatures enables the usage Docker Swarm features in the application if it has detected that it is running in a Docker Swarm environment
	DeployConfigBaseDir         string                 `env:"DEPLOY_CONFIG_BASE_DIR" envDefault:"/"`                               // DeployConfigBaseDir is the base directory (relative to the repository root) where deployment configuration files will be searched for.
	PassEnv                     bool                   `env:"PASS_ENV"`                                                            // PassEnv controls whether environment variables from the doco-cd container should be passed to the deployment environment for docker compose variable interpolation. Use with caution, as this may expose sensitive information to the deployment environment.
	PollConfigYAML              string                 `env:"POLL_CONFIG"`                                                         // PollConfigYAML is the unparsed string containing the PollConfig in YAML format
	PollConfigFile              string                 `env:"POLL_CONFIG_FILE,file"`                                               // PollConfigFile is the file containing the PollConfig in YAML format
	PollConfig                  []PollConfig           `yaml:"-"`                                                                  // PollConfig is the YAML configuration for polling Git repositories for changes
	MaxPayloadSize              int64                  `env:"MAX_PAYLOAD_SIZE,notEmpty" envDefault:"1048576"`                      // MaxPayloadSize is the maximum size of the payload in bytes that the HTTP server will accept (default 1MB = 1048576 bytes)
	MetricsPort                 uint16                 `env:"METRICS_PORT,notEmpty" envDefault:"9120" validate:"min=1,max=65535"`  // MetricsPort is the port the prometheus metrics server will listen on
	AppriseApiURL               HttpUrl                `env:"APPRISE_API_URL" validate:"httpUrl"`                                  // AppriseApiURL is the URL of the Apprise notification service
	AppriseNotifyUrls           string                 `env:"APPRISE_NOTIFY_URLS"`                                                 // AppriseNotifyUrls is a comma-separated list of URLs to notify via the Apprise notification service
	AppriseNotifyUrlsFile       string                 `env:"APPRISE_NOTIFY_URLS_FILE,file"`                                       // AppriseNotifyUrlsFile is the file containing the AppriseNotifyUrls
	AppriseNotifyLevel          string                 `env:"APPRISE_NOTIFY_LEVEL,notEmpty" envDefault:"success"`                  // AppriseNotifyLevel is the level of notifications to send via the Apprise notification service
	SecretProvider              string                 `env:"SECRET_PROVIDER"`                                                     // SecretProvider is the secret provider/manager to use for retrieving secrets (e.g. bitwarden secrets manager)
	MaxDeploymentLoopCount      uint                   `env:"MAX_DEPLOYMENT_LOOP_COUNT,notEmpty" envDefault:"2" validate:"min=0"`  // Maximum allowed deployment loops before a forced deployment is triggered
	MaxConcurrentDeployments    uint                   `env:"MAX_CONCURRENT_DEPLOYMENTS,notEmpty" envDefault:"4" validate:"min=1"` // Maximum number of concurrent deployments allowed
}

AppConfig is used to configure this application https://github.com/caarlos0/env?tab=readme-ov-file#env-tag-options

func GetAppConfig 

func GetAppConfig() (*AppConfig, error)

GetAppConfig returns the configuration.

func (*AppConfig) ParsePollConfig added in v0.22.0 

func (cfg *AppConfig) ParsePollConfig() error

ParsePollConfig parses the PollConfig from either the PollConfigYAML string or the PollConfigFile.

type DeployConfig 

type DeployConfig struct {
	Name               string   `yaml:"name" json:"name"`                                                   // Name of the docker-compose deployment / stack
	RepositoryUrl      HttpUrl  `yaml:"repository_url" json:"repository_url" default:"" validate:"httpUrl"` // RepositoryUrl is the http URL of the Git repository to deploy
	WebhookEventFilter string   `yaml:"webhook_filter" json:"webhook_filter" default:""`                    // WebhookEventFilter is a regular expression to whitelist deployment triggers based on the webhook event payload (e.g., branch like "^refs/heads/main$" or "main", tag like "^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$" or "v[0-9]+\.[0-9]+\.[0-9]+")
	Reference          string   `yaml:"reference" json:"reference" default:""`                              // Reference is the Git reference to the deployment, e.g., refs/heads/main, main, refs/tags/v1.0.0 or v1.0.0
	WorkingDirectory   string   `yaml:"working_dir" json:"working_dir" default:"."`                         // WorkingDirectory is the working directory for the deployment
	ComposeFiles       []string ``                                                                          // ComposeFiles is the list of docker-compose files to use
	/* 136-byte string literal not displayed */
	Environment    map[string]string `yaml:"environment" json:"environment"`                           // Environment is a map of environment variables to use for variable interpolation in the compose files
	EnvFiles       []string          `yaml:"env_files" json:"env_files" default:"[\".env\"]"`          // EnvFiles is the list of dotenv files to use for variable interpolation
	RemoveOrphans  bool              `yaml:"remove_orphans" json:"remove_orphans" default:"true"`      // RemoveOrphans removes containers for services not defined in the Compose file
	PruneImages    bool              `yaml:"prune_images" json:"prune_images" default:"true"`          // PruneImages removes images that are no longer used by any service in the deployment or any other running container
	ForceRecreate  bool              `yaml:"force_recreate" json:"force_recreate" default:"false"`     // ForceRecreate forces the recreation/redeployment of containers even if the configuration has not changed
	ForceImagePull bool              `yaml:"force_image_pull" json:"force_image_pull" default:"false"` // ForceImagePull always pulls the latest version of the image tags you've specified if a newer version is available
	Timeout        int               `yaml:"timeout" json:"timeout" default:"180"`                     // Timeout is the time in seconds to wait for the deployment to finish in seconds before timing out
	BuildOpts      struct {
		ForceImagePull bool              `yaml:"force_image_pull" json:"force_image_pull" default:"false"` // ForceImagePull always attempt to pull a newer version of the image
		Quiet          bool              `yaml:"quiet" json:"quiet" default:"false"`                       // Quiet suppresses the build output
		Args           map[string]string `yaml:"args" json:"args"`                                         // BuildArgs is a map of build-time arguments to pass to the build process
		NoCache        bool              `yaml:"no_cache" json:"no_cache" default:"false"`                 // NoCache disables the use of the cache when building images
	} `yaml:"build_opts"` // BuildOpts is the build options for the deployment
	GitDepth    int  `yaml:"git_depth" json:"git_depth" default:"0"` // GitDepth limits the number of commits to fetch. 0 means use global GIT_CLONE_DEPTH. A positive value overrides the global setting.
	Destroy     bool `yaml:"destroy" json:"destroy" default:"false"` // Destroy removes the deployment and all its resources from the Docker host
	DestroyOpts struct {
		RemoveVolumes bool `yaml:"remove_volumes" json:"remove_volumes" default:"true"` // RemoveVolumes removes the volumes used by the deployment (always enabled in docker swarm mode)
		RemoveImages  bool `yaml:"remove_images" json:"remove_images" default:"true"`   // RemoveImages removes the images used by the deployment (currently not supported in docker swarm mode)
		RemoveRepoDir bool `yaml:"remove_dir" json:"remove_dir" default:"true"`         // RemoveRepoDir removes the repository directory after the deployment is destroyed
	} `yaml:"destroy_opts" json:"destroy_opts"` // DestroyOpts is the destroy options for the deployment
	Profiles         []string                     `yaml:"profiles" json:"profiles" default:"[]"`              // Profiles is a list of profiles to use for the deployment, e.g., ["dev", "prod"]. See https://docs.docker.com/compose/how-tos/profiles/
	ExternalSecrets  map[string]ExternalSecretRef `yaml:"external_secrets" json:"external_secrets"`           // ExternalSecrets maps env vars to legacy string references or structured references (e.g. webhook store_ref/remote_ref).
	AutoDiscover     bool                         `yaml:"auto_discover" json:"auto_discover" default:"false"` // AutoDiscover enables autodiscovery of services to deploy in the working directory by checking for subdirectories with docker-compose files
	AutoDiscoverOpts struct {
		ScanDepth int  `yaml:"depth" json:"depth" default:"0"`      // ScanDepth is the maximum depth of subdirectories to scan for docker-compose files
		Delete    bool `yaml:"delete" json:"delete" default:"true"` // Delete removes obsolete auto-discovered deployments that are no longer present in the repository
	} `yaml:"auto_discover_opts" json:"auto_discover_opts"` // AutoDiscoverOpts are options for the autodiscovery feature
	Reconciliation struct {
		Enabled        bool     `yaml:"enabled" json:"enabled" default:"true"`               // Enabled enables the reconciliation feature
		Events         []string `yaml:"events" json:"events" default:"[\"unhealthy\"]"`      // Events is the list of Docker container actions that trigger reconciliation
		RestartTimeout int      `yaml:"restart_timeout" json:"restart_timeout" default:"10"` // RestartTimeout is the timeout in seconds to wait before killing a container during a restart (used for restart-oriented reconciliation events)
		RestartSignal  string   `yaml:"restart_signal" json:"restart_signal" default:""`     // RestartSignal is the signal sent to stop containers during a restart. If not set, the default of the Docker daemon is used (SIGTERM).
		RestartLimit   int      `yaml:"restart_limit" json:"restart_limit" default:"5"`      // RestartLimit suppresses further unhealthy-triggered restarts after this many restarts in the configured window. Set to 0 to disable suppression.
		RestartWindow  int      `yaml:"restart_window" json:"restart_window" default:"300"`  // RestartWindow is the time window in seconds used with RestartLimit.
	} `yaml:"reconciliation" json:"reconciliation"` // Reconciliation is the configuration for the reconciliation feature
	Internal struct {
		File        string            `yaml:"-"` // File is the path to the deployment configuration file in the repository (if RepositoryUrl is not set) or in the cloned repository (if RepositoryUrl is set)
		Environment map[string]string // Environment is stores environment variables for variable interpolation in the compose project
		Hash        string            `yaml:"-"` // Hash is a hash of the DeployConfig struct (without changing the order of its elements)
	} // Internal holds internal configuration values that are not set by the user
}

DeployConfig is the structure of the deployment configuration file.

func DefaultDeployConfig 

func DefaultDeployConfig(name, reference string) *DeployConfig

DefaultDeployConfig creates a DeployConfig with default values.

func GetDeployConfigFromYAML added in v0.22.0 

func GetDeployConfigFromYAML(f string) ([]*DeployConfig, error)

GetDeployConfigFromYAML reads a YAML file and unmarshals it into a slice of DeployConfig structs.

func GetDeployConfigs added in v0.11.0 

func GetDeployConfigs(repoRoot, deployConfigBaseDir, name, customTarget, reference string) ([]*DeployConfig, error)

GetDeployConfigs returns either the deployment configuration from the repository or the default configuration.

func ResolveDeployConfigs added in v0.48.0 

func ResolveDeployConfigs(poll PollConfig, repoRoot, deployConfigBaseDir, name string) ([]*DeployConfig, error)

ResolveDeployConfigs returns deployment configs for a poll run, preferring inline deployments defined on the PollConfig when provided. Falls back to repository configuration files or default values when no inline deployments are present. repoRoot is the absolute path to the repository root. deployConfigBaseDir is the relative path from repo root where config files are located.

func (*DeployConfig) Hash added in v0.59.0 

func (c *DeployConfig) Hash() (string, error)

Hash returns a hash of the DeployConfig struct (without changing the order of its elements).

func (*DeployConfig) LogValue added in v0.59.0 

func (c *DeployConfig) LogValue() slog.Value

LogValue implements the slog.LogValuer interface for DeployConfig.

func (*DeployConfig) ResolveGitDepth added in v0.82.0 

func (c *DeployConfig) ResolveGitDepth(globalDepth int) int

ResolveGitDepth returns the effective git clone depth. If the deploy-level GitDepth is > 0, it overrides the global value. Otherwise the global depth is used. 0 means full clone (no limit).

func (*DeployConfig) UnmarshalYAML 

func (c *DeployConfig) UnmarshalYAML(unmarshal func(any) error) error

type EnvVarFileMapping added in v0.36.0 

type EnvVarFileMapping struct {
	EnvName    string  // EnvName is the name/key of the environment variable (e.g. API_SECRET)
	EnvValue   *string // EnvValue is the value of the environment variable
	FileValue  *string // FileValue is the content of the file that is specified in the environment variable (e.g. API_SECRET_FILE)
	AllowUnset bool    // AllowUnset indicates if both the fileField and value can be unset
}

EnvVarFileMapping holds the mappings for file-based environment variables.

type ExternalSecretRef added in v0.80.0 

type ExternalSecretRef struct {
	// LegacyRef holds the raw string value when the reference is written as a
	// plain scalar in YAML (e.g. `DB_PASSWORD: 138e3a97-ed58-431c-b366-b35500663411`).
	// Used by all non-webhook secret providers. Empty for structured refs.
	LegacyRef string `json:"-"`

	// StoreRef is the name of the global webhook secret store to use, as defined
	// in the store YAML file (e.g. `store_ref: bitwarden-login`).
	// Used exclusively by the webhook provider.
	StoreRef string `json:"store_ref,omitempty"`

	// RemoteRef contains the dynamic key/value pairs that are substituted into
	// the store's URL, headers, body and json_path templates at resolution time
	// (e.g. `key`, `property`, or any custom field the store templates reference).
	// Used exclusively by the webhook provider.
	RemoteRef map[string]any `json:"remote_ref,omitempty"`
}

ExternalSecretRef represents one external secret reference in deploy config. It supports legacy scalar references (for existing providers like Bitwarden SM, 1Password, AWS Secrets Manager etc.) and structured object references used by the webhook provider's store-based model.

func (*ExternalSecretRef) EncodedReference added in v0.80.0 

func (r *ExternalSecretRef) EncodedReference() (string, error)

EncodedReference returns the string representation sent to provider implementations. Legacy refs are returned as-is; structured refs are encoded as JSON.

func (*ExternalSecretRef) UnmarshalYAML added in v0.80.0 

func (r *ExternalSecretRef) UnmarshalYAML(node *yaml.Node) error

type HttpUrl added in v0.17.0 

type HttpUrl string // HttpUrl is a type for strings that represent HTTP URLs

type PollConfig added in v0.22.0 

type PollConfig struct {
	CloneUrl     HttpUrl         `yaml:"url" json:"url" validate:"httpUrl"`                    // CloneUrl is the URL to clone the Git repository that is used to poll for changes
	Reference    string          `yaml:"reference" json:"reference" default:"refs/heads/main"` // Reference is the Git reference to the deployment, e.g., refs/heads/main, main, refs/tags/v1.0.0 or v1.0.0
	Interval     int             `yaml:"interval" default:"180"`                               // Interval is the interval in seconds to poll for changes
	CustomTarget string          `yaml:"target" json:"target" default:""`                      // CustomTarget is the name of an optional custom deployment config file, e.g. ".doco-cd.custom-name.yaml"
	RunOnce      bool            `yaml:"run_once" default:"false"`                             // RunOnce when true, performs a single run and exits
	Deployments  []*DeployConfig `yaml:"deployments" json:"deployments" default:"[]"`          // Deployments allows defining deployment configs inline in the poll configuration
}

func (PollConfig) LogValue added in v0.59.0 

func (c PollConfig) LogValue() slog.Value

LogValue implements the slog.LogValuer interface for PollConfig.

func (*PollConfig) String added in v0.22.0 

func (c *PollConfig) String() string

String returns a string representation of the PollConfig.

func (*PollConfig) UnmarshalJSON added in v0.76.0 

func (c *PollConfig) UnmarshalJSON(data []byte) error

func (*PollConfig) UnmarshalYAML added in v0.22.0 

func (c *PollConfig) UnmarshalYAML(unmarshal func(any) error) error

func (*PollConfig) Validate added in v0.22.0 

func (c *PollConfig) Validate() error

Validate checks if the PollConfig is valid.

type PollJob added in v0.22.0 

type PollJob struct {
	Config  PollConfig // config is the PollConfig for this instance
	LastRun int64      // LastRun is the last time this instance ran
	NextRun int64      // NextRun is the next time this instance should run
}

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.