How CasaOS Handles Configuration from Config Files and Environment Variables

CasaOS loads INI-style configuration files into strongly-typed Go structs at startup, then allows environment variables to override specific values via direct os.Getenv calls throughout the codebase.

CasaOS is an open-source home server system built in Go that centralizes its configuration management in the config package. The system implements a two-step initialization process that first parses static INI files into global structs, then applies runtime environment variable overrides to support flexible deployment scenarios. This hybrid approach ensures CasaOS can handle configuration from config files and environment variables deterministically while maintaining strong type safety.

Configuration from Config Files and Environment Variables: The Two-Step Architecture

CasaOS employs a hybrid configuration strategy that separates static file-based settings from dynamic runtime overrides. This architecture allows the system to use version-controlled configuration files while still supporting containerized deployments where environment variables are preferred.

File-Based Configuration (INI Parsing)

At startup, the config package reads an INI-style configuration file using the github.com/go-ini/ini library. The file path defaults to a standard location but can be overridden via the CASAOS_CONFIG environment variable. The InitSetup function in pkg/config/init.go handles the file discovery, creation of default files if missing, and parsing of sections into strongly-typed Go structs like AppInfo, ServerInfo, and SystemConfigInfo.

Environment Variable Overrides

After the initial file load, the system checks for environment variables that override specific values. Throughout the codebase, direct calls to os.Getenv allow runtime injection of settings such as CASAOS_RUNTIME_PATH for directory locations or CASAOS_HTTP_PORT for server binding. These overrides update the global configuration structs dynamically without requiring file modifications.

Configuration Initialization Flow

The initialization sequence in pkg/config/init.go follows a deterministic eight-step process that establishes the configuration state before the server begins accepting requests.

First, InitSetup determines the configuration file path. It defaults to CasaOSConfigFilePath but accepts an override through the function parameter or the CASAOS_CONFIG environment variable. If the resolved path does not exist, the function writes a sample configuration file provided by the caller.

Next, the system loads the INI file and maps each section to its corresponding struct. The mapTo function iterates through sections—app, server, system, file, and common—populating package-level global variables that remain accessible for the process lifetime.

func InitSetup(config string, sample string) {
    ConfigFilePath = CasaOSConfigFilePath          // default path
    if len(config) > 0 {                           // env‑override
        ConfigFilePath = config
    }

    // Create a default file if it does not exist …
    if _, err := os.Stat(ConfigFilePath); os.IsNotExist(err) {
        // ...
        file.WriteString(sample)
    }

    // Load and map the file
    Cfg, err = ini.Load(ConfigFilePath)
    mapTo("app",    AppInfo)
    mapTo("server", ServerInfo)
    // ...
}

After initialization, no further file I/O occurs during normal operation. All configuration reads access the pre-populated global structs, ensuring high performance and thread safety.

Runtime Environment Variable Overrides

While the INI file provides the base configuration, CasaOS checks environment variables at specific integration points to enable dynamic reconfiguration without restarting the service. This pattern appears throughout service initializers and system handlers.

In service/system.go, the HTTP port can be overridden programmatically, with the code updating both the runtime struct and the underlying INI configuration:

// Example from service/system.go – overriding HTTP port
if len(port) > 0 && port != config.ServerInfo.HttpPort {
    config.Cfg.Section("server").Key("HttpPort").SetValue(port)
    config.ServerInfo.HttpPort = port
    config.Cfg.SaveTo(config.SystemConfigInfo.ConfigPath)
}

For path-based configurations, the system typically uses direct environment checks:

runtimePath := os.Getenv("CASAOS_RUNTIME_PATH")
if runtimePath != "" {
    config.CommonInfo.RuntimePath = runtimePath
}

These environment checks occur during service initialization and specific runtime operations, allowing container orchestrators to inject values such as database paths, API tokens, or network binding addresses.

Global Struct Access Pattern

Once initialized, the configuration structs serve as a single source of truth across the entire CasaOS codebase. Other packages import github.com/IceWhaleTech/CasaOS/pkg/config and reference the global variables directly.

In route/v2.go, the server address construction demonstrates this pattern:

// In a handler – reading the server address
addr := fmt.Sprintf("%s:%s", config.ServerInfo.HttpHost, config.ServerInfo.HttpPort)

This approach eliminates the need for repeated file parsing or environment variable lookups during request handling. The global structs contain the final resolved values, whether sourced from the INI file or overridden via environment variables during startup.

Key Configuration Files

Understanding the CasaOS configuration system requires familiarity with these specific source files:

• pkg/config/init.go: Contains the core InitSetup function and global struct definitions. This file handles INI parsing and the initial mapping to typed structs.

• service/system.go: Implements runtime configuration updates and demonstrates how the system handles dynamic port changes and path overrides through environment variables.

• route/init.go: The entry point that invokes config.InitSetup early in the server startup sequence, ensuring configuration is available before routes are registered.

• pkg/utils/httper/httper.go: Shows practical usage of config.ServerInfo values for constructing external API calls and service discovery.

• conf/conf.conf.sample: Provides the reference INI structure shipped with the repository, documenting available sections and keys.

Summary

• CasaOS handles configuration from config files by parsing INI files at startup into strongly-typed Go structs (AppInfo, ServerInfo, etc.) using the github.com/go-ini/ini library.
• Environment variables override file settings through direct os.Getenv calls in service initializers, with key variables including CASAOS_CONFIG, CASAOS_RUNTIME_PATH, and CASAOS_HTTP_PORT.
• Global access pattern stores configuration in package-level variables within pkg/config, providing high-performance, thread-safe reads across the codebase without repeated file I/O.
• Runtime flexibility allows the system to update configuration values programmatically and persist changes back to the INI file while running.

Frequently Asked Questions

How does CasaOS determine which configuration file to load?

CasaOS defaults to a predefined path stored in CasaOSConfigFilePath, but checks for the CASAOS_CONFIG environment variable during initialization. If set, the InitSetup function in pkg/config/init.go uses that path instead, creating a default file from the provided sample if the path does not exist.

Can environment variables completely replace the INI configuration file?

No, the INI file serves as the primary configuration source. Environment variables provide targeted overrides for specific values like paths and ports. The system requires the INI file to exist at startup, though it will generate a default file from a sample if missing.

Where does CasaOS store runtime configuration changes?

When the system modifies configuration at runtime—such as when changing the HTTP port in service/system.go—it updates both the global struct in memory and the underlying INI file. The SaveTo method on the ini.File object persists changes to disk, ensuring consistency between the running state and the file-based configuration.

Is the CasaOS configuration thread-safe after initialization?

Yes. Since all configuration values are loaded into global structs during the single initialization phase in pkg/config/init.go, subsequent reads across goroutines access immutable memory. The system does not support hot-reloading of configuration files; changes require a process restart or explicit runtime updates through the API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}