Configuration

Copper reads configuration from TOML files in the ./config directory. A new project ships with base.toml, dev.toml, and prod.toml. Shared values go in base.toml, while each environment’s file overrides what it needs.

Extending Files

Config files declare what they build on with the extends key:

config/dev.toml

extends = ["base.toml"]

[rockets]
launch_site = "canaveral"
enable_telemetry = true

Running with dev.toml loads everything from base.toml plus the values above. The extending file itself wins when keys collide with an extended file; between files in the extends list, earlier ones win.

Avoid top-level configuration values. Group everything under a section so that each package can load its own config without a shared “global” struct.

Choosing a Config File

The -config flag selects which file to load. It defaults to ./config/dev.toml:

./build/app.out -config=./config/prod.toml

For one-off overrides, you may use -set with TOML syntax. Separate multiple overrides with ;:

./build/app.out -set "chttp.port=5902;clogger.format='json'"

Reading Config in Your Package

Each package loads its own section with cconfig.Loader. By convention this lives in config.go:

pkg/rockets/config.go

package rockets

import (
	"github.com/gocopper/copper/cconfig"
	"github.com/gocopper/copper/cerrors"
)

type Config struct {
	LaunchSite      string `toml:"launch_site"`
	EnableTelemetry bool   `toml:"enable_telemetry"`
}

func LoadConfig(configs cconfig.Loader) (Config, error) {
	var config Config

	err := configs.Load("rockets", &config)
	if err != nil {
		return Config{}, cerrors.New(err, "failed to load rockets config", nil)
	}

	return config, nil
}

Add LoadConfig to the package’s WireModule and take Config as a field on any params struct that needs it. If the section is missing from the config file, Load is a no-op and your struct keeps its zero values. For keys omitted from a section that is present, you may set defaults with the default tag. If you would like to cover a missing section as well, apply defaults after loading:

type Config struct {
	MaxCrew int `toml:"max_crew" default:"6"`
}

Environment Variables

Config files are rendered as Go templates before parsing, with all environment variables available under .EnvVars:

config/prod.toml

[csql]
dsn = "{{ .EnvVars.DATABASE_URL }}"

Secrets

There are two patterns for keeping secrets out of your repository. For development, put secrets in a gitignored file and pull it in via extends:

config/dev.toml

extends = ["base.toml", "local.toml"]

Consider checking in a local_example.toml with the shape of the file and blank values, so that new teammates know what to fill in. For production, use the exec template function to fetch secrets from a secret manager at startup. The command runs through sh -c and its trimmed stdout is substituted in:

config/prod.toml

[csql]
dsn = "{{ exec "gcloud secrets versions access latest --secret=DATABASE_URL" }}"

Since the secret is fetched when the app boots, it never touches your repository or your process environment.

Getting Started

The Basics

Architecture

HTTP

Database

Frontend

Digging Deeper

Reference

Extending Files

Choosing a Config File

Reading Config in Your Package

Environment Variables

Secrets

​Extending Files

​Choosing a Config File

​Reading Config in Your Package

​Environment Variables

​Secrets

Extending Files

Choosing a Config File

Reading Config in Your Package

Environment Variables

Secrets