How to Configure CasaOS Using Environment Variables and Config Files

CasaOS reads its runtime configuration from an INI-style file that can be relocated using the CASAOS_CONFIG environment variable or the -c command-line flag, with sections mapping directly to Go structs for application paths, server ports, and system settings.

CasaOS is an open-source home cloud system that centralizes its configuration in a single INI file. Understanding how to manipulate this file and override its location is essential for containerized deployments, systemd units, and custom data directory setups. The configuration system is implemented in the IceWhaleTech/CasaOS repository using a hierarchical precedence model where environment variables take priority over CLI flags.

Configuration File Location and Defaults

By default, CasaOS builds its configuration path using the DefaultConfigPath constant defined in common/constants.go, appending casaos.conf as the filename. If this file does not exist at startup, the system automatically copies the sample configuration from build/sysroot/etc/casaos/casaos.conf.sample to the default location.

This initialization logic resides in pkg/config/init.go, specifically within the InitSetup function. When the binary starts, it checks for the file's existence and creates it from the sample if necessary, ensuring the system always has a valid configuration to load.

Overriding the Config Path

CasaOS provides two mechanisms for specifying an alternative configuration file location, checked in a specific order of precedence.

Using the CASAOS_CONFIG Environment Variable

The highest priority method is setting the CASAOS_CONFIG environment variable. In pkg/config/init.go, the InitSetup function explicitly checks for this variable before processing any command-line flags:

// pkg/config/init.go (excerpt)
if envPath := os.Getenv("CASAOS_CONFIG"); envPath != "" {
    ConfigFilePath = envPath
}

When this variable is set, it overrides both the default path and any value passed via the -c flag. This makes it ideal for Docker containers and systemd service files where environment-based configuration is preferred.

Using the -c Command-Line Flag

The binary accepts a -c flag parsed in main/main.go using Go's flag package:

// main/main.go
configFlag = flag.String("c", "", "config address")
// ...
config.InitSetup(*configFlag, _confSample)   // line 68

If provided and the environment variable is unset, this value is passed to InitSetup and used as the configuration path. This method is useful for scripts and development environments where you might maintain multiple configuration profiles.

Understanding the Configuration File Structure

The casaos.conf file uses INI syntax with sections that map directly to Go structs via the go-ini library. During initialization in pkg/config/init.go (lines 72-83), the system calls ini.Load followed by mapTo for each section to populate the runtime models.

The primary configuration sections include:

• [app] – Maps to model.APPModel, controlling paths for the database (DBPath), logs (LogPath), and shell scripts.
• [server] – Maps to model.ServerModel, defining the HTTP port (HttpPort) and API address.
• [system] – Maps to model.SystemConfig, containing system-wide toggles for debug mode and UI settings.
• [file] – Maps to model.FileSetting, managing file-related defaults and share paths.
• [common] – Maps to model.CommonModel, specifying runtime paths for temporary files.

Runtime Configuration Updates

CasaOS supports modifying configuration values during runtime and persisting them back to disk. The configuration object exposes a SaveTo method that writes changes to the file path specified at startup.

For example, after successfully changing the HTTP port, the system clears the port value from memory and saves the updated configuration back to disk, as seen in main/main.go (lines 81-88):

// main/main.go
config.Cfg.Section("server").Key("HttpPort").SetValue("")
config.Cfg.SaveTo(config.ConfigFilePath)

This ensures that configuration changes made through the UI or API persist across service restarts.

Practical Configuration Examples

Relocating Data Directories

To move CasaOS data to a custom location, create a configuration file with modified [app] section paths:

# Copy the sample configuration

cp build/sysroot/etc/casaos/casaos.conf.sample /etc/casaos/casaos.conf

Edit /etc/casaos/casaos.conf to specify new paths:

[app]
DBPath = /mnt/mydata/casaos
LogPath = /mnt/mydata/casaos/log

Launch CasaOS using the environment variable:

export CASAOS_CONFIG=/etc/casaos/casaos.conf
casaos

Alternatively, use the CLI flag:

casaos -c /etc/casaos/casaos.conf

Custom Port Configuration

To run CasaOS on a non-standard port, modify the [server] section before starting:

[server]
HttpPort = 8080

Save the file and launch with your preferred override method. CasaOS will bind to port 8080 instead of the default.

Summary

• CasaOS uses a single INI file (casaos.conf) for all runtime configuration, located by default using the DefaultConfigPath constant.
• Environment variable CASAOS_CONFIG takes precedence over all other methods for specifying the config file location.
• Command-line flag -c provides a secondary override method, parsed in main/main.go and processed in pkg/config/init.go.
• Configuration sections (app, server, system, file, common) map to Go structs and control everything from database paths to HTTP ports.
• Runtime updates are persisted via Cfg.SaveTo, allowing the system to update its own configuration after changes like port modifications.

Frequently Asked Questions

What is the default location of the CasaOS configuration file?

The default path is constructed from the DefaultConfigPath constant defined in common/constants.go combined with the filename casaos.conf. On most systems, this resolves to /etc/casaos/casaos.conf. If the file does not exist at startup, CasaOS automatically copies the sample from build/sysroot/etc/casaos/casaos.conf.sample to this location.

Does the CASAOS_CONFIG environment variable override the -c flag?

Yes. According to the initialization logic in pkg/config/init.go, the system checks os.Getenv("CASAOS_CONFIG") before processing the value passed via the -c flag. If the environment variable is set, it is used regardless of whether a flag was also provided. This design ensures that container and systemd environments can enforce specific configuration paths independently of command-line arguments.

Can I modify CasaOS configuration without restarting the service?

CasaOS can persist certain runtime changes to disk without requiring a full restart. The configuration object loaded via ini.Load provides a SaveTo method that writes current values back to ConfigFilePath. For example, the system uses this mechanism to clear the HTTP port value from the config file after successfully binding to a new port, as implemented in main/main.go lines 81-88.

What configuration sections are available in casaos.conf?

The configuration file supports five primary sections that map to specific Go structs: [app] (paths and directories), [server] (network settings), [system] (global toggles), [file] (file management settings), and [common] (runtime temporary paths). Each section is parsed using mapTo functions in pkg/config/init.go to populate the corresponding models used throughout the application.

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