Environment

CoreGo is configured through environment variables, optionally kept in a .env file during development. The facade loads them for you: corego.New calls env.Load() once at startup, reads the variables listed below and exposes the snapshot as core.Env. You only need the env package directly when you use CoreGo's packages standalone or want typed access to your own variables.

core, err := corego.New(nil) // reads ./.env (when present) + the process environment
if err != nil {
	log.Fatal(err) // for example a malformed .env file
}
fmt.Println(core.Env.AppURL)                 // "http://localhost:8080" by default
workers := core.Env.Int("WORKERS", 4)        // your own variables, typed

If your application needs its own settings before it builds the corego.Config (for example to choose options from them), load the environment yourself and hand the snapshot to the facade through Config.Env. corego.New then uses it as-is and does not read .env again; core.Env is that same snapshot:

e, err := env.Load()
if err != nil {
	log.Fatal(err)
}
core, err := corego.New(&corego.Config{
	Env: e, // reuse the snapshot: .env is read once
	Auth: &corego.AuthOptions{
		Service: auth.Config{SessionTTL: e.Duration("SESSION_TTL", 7*24*time.Hour)}, // your own variable
	},
})
if err != nil {
	log.Fatal(err)
}

Every variable CoreGo readsCopy Anchor Link

Values configured in code win over the environment: a variable is only consulted when the matching field in corego.Config is left nil or empty. The two boolean switches COREGO_REQUIRE_VERIFIED_EMAIL and COREGO_AUTH_COOKIE are the exception: they can only turn a feature on, so the effective setting is the code value or the environment value. The COREGO_* auth variables are read only when auth is enabled (Config.Auth is set).

Boolean variables accept 1, t, true, TRUE, True and 0, f, false, FALSE, False. For COREGO_REQUIRE_VERIFIED_EMAIL, COREGO_AUTH_COOKIE and COREGO_BANNER anything else (yes, on, a typo) makes corego.New return an error naming the variable, and so does an unknown COREGO_MAIL value: a mistyped security switch stops the application instead of being ignored. The auth variables are validated whenever auth is enabled, even when a code setting makes them irrelevant; COREGO_BANNER is validated on every start. TRUST_PROXY_HEADERS follows the same strict rule whenever ServerOptions.TrustProxyHeaders is nil.

With auth enabled, corego.New ends with one Info line that shows what the environment and the code resolved to:

INFO corego: auth ready store=postgres table_prefix=corego_ base_path=/auth mail=smtp require_verified_email=true cookie=false

store is memory, mongo, postgres or custom (AuthOptions.CustomStore; table_prefix is only shown for the database stores), and mail is smtp, log, custom (AuthOptions.Service.Mailer or AuthOptions.MailSender) or none.

CoreGo's own integration tests additionally read COREGO_TEST_MONGO_URL and COREGO_TEST_POSTGRES_URL; applications never need them (see testing.md).

The repository ships .env.example with every variable and a one-line explanation. Copy it to .env and uncomment what you need:

cp .env.example .env

Never commit your real .env; it usually contains passwords.

PrecedenceCopy Anchor Link

1. Code wins. A value set in corego.Config is used as-is; the environment is only a fallback. The exception are the on-only switches COREGO_REQUIRE_VERIFIED_EMAIL and COREGO_AUTH_COOKIE (code OR environment).
2. The process environment wins over .env. .env only fills in variables that are not set at all. A variable exported in your shell, by Docker or by your hosting platform always takes precedence.
3. Set-but-empty still counts as set. PORT= in the process environment blocks PORT=4000 in .env; the typed field then falls back to its default (8080). To let .env supply a value, unset the variable.

For the typed fields and the typed getters an empty or whitespace-only value means "not configured": Env.MongoURL is "", Env.Int returns your default, and so on. Surrounding whitespace is trimmed.

The env packageCopy Anchor Link

LoadingCopy Anchor Link

import "github.com/berkkaradalan/CoreGo/env"

e, err := env.Load() // ./.env when present + the process environment
if err != nil {
	log.Fatal(err)
}

e, err = env.LoadFile("config/staging.env") // explicit file, must exist

Parse errors name the file and line but never echo its contents, so secrets cannot leak into logs:

env: parse .env: line 3: unterminated quoted value

Loading never modifies the process environment: os.Getenv does not see values that exist only in .env. Read them through the returned Env.

Typed fieldsCopy Anchor Link

Reading your own variablesCopy Anchor Link

key, ok := e.Get("STRIPE_KEY")                       // raw value, and whether it is set
region := e.GetOrDefault("AWS_REGION", "eu-west-1")  // trimmed value or the default
workers := e.Int("WORKERS", 4)                       // base-10 integer
debug := e.Bool("DEBUG", false)                      // strconv.ParseBool
timeout := e.Duration("HTTP_TIMEOUT", 30*time.Second) // "30s", "5m", "1h30m"
hosts := e.Strings("ALLOWED_HOSTS")                  // "a.com, b.com" -> ["a.com" "b.com"]

Invalid values never cause an error or a panic; validate them yourself when a typo must stop the application:

if raw, ok := e.Get("WORKERS"); ok {
	if _, err := strconv.Atoi(strings.TrimSpace(raw)); err != nil {
		log.Fatalf("WORKERS must be an integer, got %q", raw)
	}
}

Snapshot semanticsCopy Anchor Link

An Env is a snapshot taken by Load: later os.Setenv calls and later edits to .env are invisible to it. Configuration therefore stays constant for the lifetime of the process. An Env is read-only and safe for concurrent use.

The .env file formatCopy Anchor Link

# Comments start with #
PORT=8080
APP_NAME="My App"                 # double quotes; \n inside becomes a newline
GREETING='Hello $NAME'            # single quotes: taken literally
export SMTP_HOST=smtp.example.com # a leading "export" is allowed
DB_HOST=localhost
DATABASE_URL=postgres://app:secret@${DB_HOST}:5432/app

• ${NAME} expands only variables defined earlier in the same file; the process environment is not visible to expansion.
• Variable names may contain letters, digits, _ and .. A line without a name (=value), a name with spaces (MY VAR=1) or a bare word without = is a parse error.
• Windows line endings are accepted.

Testing code that reads the environmentCopy Anchor Link

Use t.Setenv for process variables and LoadFile (or t.Chdir into a temporary directory with a .env) for files. Both are restored automatically when the test ends:

func TestConfig(t *testing.T) {
	t.Setenv("WORKERS", "8")

	path := filepath.Join(t.TempDir(), "test.env")
	if err := os.WriteFile(path, []byte("APP_URL=https://test.example.com\n"), 0o600); err != nil {
		t.Fatal(err)
	}

	e, err := env.LoadFile(path)
	if err != nil {
		t.Fatal(err)
	}
	if e.Int("WORKERS", 1) != 8 || e.AppURL != "https://test.example.com" {
		t.Fatalf("unexpected config: %+v", e)
	}
}