env

Documentation

Overview

Package env implements multi-environment management for nSelf projects. Each environment (dev, staging, prod) has its own .env file, Docker project name, network, and volume namespace to enable side-by-side operation.

legacy_bios.go — P97 G0-T02

nSelf was internally referred to as "BIOS" in pre-v1.0 (alpha) builds. A handful of long-running self-hosted deployments still ship .env files with the legacy BIOS_* prefixes. To avoid silently breaking those operators on upgrade, this file provides a one-way mapping from BIOS_* env vars to the canonical NSELF_* names. Any caller that loads env vars at startup can invoke ApplyLegacyBIOSFallback once and have legacy values transparently promoted to the new names.

Policy:

• The new (NSELF_*) name always wins. We never overwrite a value that the operator has already set under the canonical name.
• When a legacy var is promoted, we emit a one-shot deprecation warning to stderr listing the mapping. Subsequent calls in the same process are silent (so build/start/etc don't spam the warning N times).
• Sunset version: BIOS_* support will be removed in v1.2.0. The warning advertises this so operators have a deadline.

Index

• Constants
• Variables
• func ActiveEnv(projectDir string) string
• func Copy(projectDir, fromEnv, toEnv string) error
• func DockerProjectName(projectName, env string) string
• func SetActiveEnv(projectDir, env string) error
• func ShiftPort(basePort int, env string) int
• type DiffEntry
  • func Diff(projectDir, envA, envB string) ([]DiffEntry, error)
• type EnvInfo
  • func List(projectDir string) []EnvInfo
• type KeyValue
  • func Show(projectDir, env string) ([]KeyValue, error)
• type LegacyBIOSPromotion
  • func ApplyLegacyBIOSFallback() []LegacyBIOSPromotion

Constants

const DefaultEnv = "dev"

DefaultEnv is the environment used when none is explicitly set.

const LegacyBIOSSunsetVersion = "v1.2.0"

LegacyBIOSSunsetVersion is the nSelf release after which BIOS_* env vars will no longer be honoured. Surfaced in the deprecation warning so operators know the cutoff.

Variables

var PortShifts = map[string]int{
	"dev":     0,
	"staging": 100,
	"prod":    200,
}

PortShifts maps environment names to port offset values. dev=default, staging=+100, prod=+200.

Functions

func ActiveEnv

func ActiveEnv(projectDir string) string

ActiveEnv reads the currently active environment from .nself/active_env. Returns DefaultEnv if the file does not exist.

func Copy

func Copy(projectDir, fromEnv, toEnv string) error

Copy scaffolds a new environment by copying an existing one.

func DockerProjectName

func DockerProjectName(projectName, env string) string

DockerProjectName returns the Docker Compose project name for a given project and environment: nself-{project}-{env}.

func SetActiveEnv

func SetActiveEnv(projectDir, env string) error

SetActiveEnv writes the active environment to .nself/active_env.

func ShiftPort

func ShiftPort(basePort int, env string) int

ShiftPort applies the environment port offset to a base port.

Types

type DiffEntry

type DiffEntry struct {
	Key    string
	ValueA string // value in env A (empty = not present)
	ValueB string // value in env B (empty = not present)
}

DiffEntry describes a difference between two environments.

func Diff

func Diff(projectDir, envA, envB string) ([]DiffEntry, error)

Diff compares two environment configs and returns differences.

type EnvInfo

type EnvInfo struct {
	Name   string
	Active bool
	File   string
}

EnvInfo describes an available environment.

func List

func List(projectDir string) []EnvInfo

List returns all available environments for a project by scanning for .env.{name} files plus the active env.

type KeyValue

type KeyValue struct {
	Key   string
	Value string
}

KeyValue is a key-value pair from an env file.

func Show

func Show(projectDir, env string) ([]KeyValue, error)

Show returns key-value pairs for the given environment with secrets redacted.

type LegacyBIOSPromotion

type LegacyBIOSPromotion struct {
	Legacy    string
	Canonical string
	Value     string // value that was copied (redacted upstream when logged)
}

LegacyBIOSPromotion records a single (legacy, canonical) promotion.

func ApplyLegacyBIOSFallback

func ApplyLegacyBIOSFallback() []LegacyBIOSPromotion

ApplyLegacyBIOSFallback promotes any BIOS_* env var to its canonical NSELF_* equivalent when the canonical name is unset. Returns the slice of (legacy, canonical) pairs that were promoted in this call, primarily so tests can assert behaviour deterministically.

The function uses os.Getenv / os.Setenv on the real process environment. The (legacy, canonical) pairs that were promoted are returned in a deterministic alphabetical order (by legacy name) so callers can rely on stable output for assertions and structured logs.

On the first call that promotes at least one variable, a one-shot deprecation warning is written to stderr listing the mapping table and the sunset version. Subsequent calls in the same process do not re-print even if more variables are promoted.