How CasaOS Handles Configuration Initialization and the casaos.conf File

CasaOS initializes its configuration by loading a plain-text INI file (casaos.conf) through a deterministic startup sequence that creates a default from an embedded sample if the file is missing, mapping sections to strongly-typed structs for global access.

CasaOS uses a robust configuration system defined in the pkg/config package to bootstrap its runtime environment from a single INI file. According to the IceWhaleTech/CasaOS source code, the initialization process guarantees that a valid casaos.conf file exists before any services or HTTP routers start, either by loading a user-supplied file or generating one from an embedded template.

The Configuration Initialization Sequence

Determining the Default File Path

The system constructs the default configuration path by joining constants.DefaultConfigPath (defined in common/constants.go as /etc/casaos) with the filename casaos.conf. In pkg/config/config.go, this path is stored in the package-level variable:

var CasaOSConfigFilePath = filepath.Join(constants.DefaultConfigPath, "casaos.conf")

Parsing the Command-Line Flag

Before the initialization routine runs, main/main.go (line 53) defines an optional -c flag that allows users to specify a custom configuration file path at startup:

$ casaos -c /custom/path/casaos.conf

Invoking the Setup Routine

The main.init() function (lines 68-70) triggers the configuration load by calling config.InitSetup(*configFlag, _confSample), passing the flag value and an embedded sample configuration.

Creating the Configuration File from Sample

If the target file does not exist, InitSetup in pkg/config/init.go (lines 46-68) creates it automatically. The function writes the embedded sample configuration—compiled into the binary from build/sysroot/etc/casaos/casaos.conf.sample—to ConfigFilePath, ensuring the system never starts with a missing configuration.

Loading and Mapping INI Sections

Once the file exists, CasaOS uses ini.Load(ConfigFilePath) to parse the INI structure into the global Cfg variable. The mapTo helper then copies values from specific sections—including [app], [server], [system], [file], and [common]—into strongly-typed structs such as AppInfo, ServerInfo, SystemConfigInfo, FileSettingInfo, and CommonInfo. These models are defined in the model package and exported from pkg/config for application-wide access.

Key Source Files in the Configuration System

• pkg/config/config.go – Defines CasaOSConfigFilePath and constructs the default path using constants.DefaultConfigPath.
• pkg/config/init.go – Contains InitSetup, which handles file creation, INI parsing, and struct mapping.
• main/main.go – Parses the -c flag, embeds the sample configuration via //go:embed, and invokes the initialization routine.
• build/sysroot/etc/casaos/casaos.conf.sample – The embedded template used to bootstrap fresh installations.
• common/constants.go – Provides DefaultConfigPath (/etc/casaos) used as the configuration directory base.

Accessing Configuration Values at Runtime

After initialization completes, any package can import github.com/IceWhaleTech/CasaOS/pkg/config to read settings. The package exports populated variables that map directly to INI sections:

import "github.com/IceWhaleTech/CasaOS/pkg/config"

func Example() {
    // Access [app] section values
    fmt.Println("Log directory:", config.AppInfo.LogPath)
    
    // Access [server] section values
    fmt.Println("HTTP port:", config.ServerInfo.HttpPort)
}

Later in main.go (lines 81-84), the HTTP router initializes using these values, and the system may modify configuration properties dynamically—such as clearing the HTTP port after a dynamic port change—while the application continues to reference the global config package variables.

Summary

• CasaOS determines the configuration path using constants.DefaultConfigPath and the filename casaos.conf.
• The -c flag in main.go allows runtime override of the configuration file location.
• config.InitSetup creates a default file from the embedded sample at build/sysroot/etc/casaos/casaos.conf.sample if no file exists.
• INI sections are mapped to strongly-typed structs (AppInfo, ServerInfo, etc.) exported by the pkg/config package.
• The configuration is globally accessible throughout the codebase after the initialization sequence completes in main.init().

Frequently Asked Questions

Where is the default casaos.conf file located?

The default location is /etc/casaos/casaos.conf, constructed by joining constants.DefaultConfigPath (defined in common/constants.go) with the filename in pkg/config/config.go.

How does CasaOS handle missing configuration files?

If the file does not exist at startup, the InitSetup function in pkg/config/init.go automatically creates it by writing the embedded sample configuration from build/sysroot/etc/casaos/casaos.conf.sample to the target path.

Can I use a custom configuration file path?

Yes. You can specify a custom path using the -c command-line flag when starting CasaOS, as implemented in main/main.go at line 53. For example: casaos -c /opt/myconfig/casaos.conf.

Which configuration sections are available in casaos.conf?

The default sample includes sections such as [app], [server], [system], [file], and [common], which are mapped to the AppInfo, ServerInfo, SystemConfigInfo, FileSettingInfo, and CommonInfo structs respectively.

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