# How to Configure CasaOS Using Environment Variables and Config Files

> Learn how to configure CasaOS using environment variables and config files. Customize application paths, server ports, and system settings for optimal performance.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/IceWhaleTech/CasaOS/blob/main/common/constants.go), appending [`casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/config/init.go), the `InitSetup` function explicitly checks for this variable before processing any command-line flags:

```go
// 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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go) using Go's `flag` package:

```go
// 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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go) (lines 81-88):

```go
// 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:

```bash

# Copy the sample configuration

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

```

Edit [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf) to specify new paths:

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

```

Launch CasaOS using the environment variable:

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

```

Alternatively, use the CLI flag:

```bash
casaos -c /etc/casaos/casaos.conf

```

### Custom Port Configuration

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

```ini
[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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go) and processed in [`pkg/config/init.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/common/constants.go) combined with the filename [`casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main/casaos.conf). On most systems, this resolves to [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/config/init.go) to populate the corresponding models used throughout the application.