# How CasaOS Configures HTTPS with Certificate and Key Files: A Complete Guide

> Learn how CasaOS configures HTTPS using certificate and key files. This guide details reading CertFile and KeyFile paths and passing them to ListenAndServeTLS.

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

---

**CasaOS enables HTTPS by reading the `CertFile` and `KeyFile` paths from the `[scheme]` section of [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf) and passing them to the Go standard library’s `ListenAndServeTLS` during gateway initialization.**

CasaOS, the open-source home cloud platform developed by IceWhaleTech, secures its API endpoints through a structured TLS configuration system defined in the Go source code. By modifying the INI-style configuration file and providing PEM-encoded certificate files, administrators can encrypt all traffic to the internal gateway. Understanding how CasaOS configures HTTPS with certificate and key files requires examining the `Scheme` struct definition, the configuration loading sequence, and the server initialization logic.

## HTTPS Configuration Model in CasaOS

### The Scheme Struct Definition

In [`internal/conf/config.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/internal/conf/config.go), CasaOS defines a `Scheme` struct that encapsulates all HTTPS-related settings. This struct contains three critical fields that control TLS behavior:

- **`Https`**: A boolean flag that toggles TLS mode on or off
- **`CertFile`**: Absolute path to the PEM-encoded TLS certificate file
- **`KeyFile`**: Absolute path to the PEM-encoded private key matching the certificate

According to the IceWhaleTech/CasaOS source code, these fields map directly to the `[scheme]` section in the configuration file.

### Configuration File Location

CasaOS reads these values from [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf), an INI-formatted configuration file. The `[scheme]` section maps to the global `AppInfo.Scheme` variable, making the certificate paths available throughout the application lifecycle.

## Loading and Mapping Configuration Values

### InitSetup Function in pkg/config/init.go

During startup, the `InitSetup` function in [`pkg/config/init.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/config/init.go) loads the configuration file using `ini.Load()` and maps the `[scheme]` section to the global configuration object.

```go
// pkg/config/init.go
Cfg, err = ini.Load(ConfigFilePath)
// ...
mapTo("scheme", &AppInfo.Scheme)

```

This process populates `config.AppInfo.Scheme.CertFile` and `config.AppInfo.Scheme.KeyFile` with the paths specified in the configuration file.

## Starting the HTTPS Server

### TLS Initialization in the Gateway

When `Scheme.Https` evaluates to `true`, the gateway component creates an `http.Server` with TLS configuration and calls `ListenAndServeTLS`, passing the certificate and key file paths from the configuration.

```go
tlsConfig := &tls.Config{
    MinVersion: tls.VersionTLS12,
}
srv := &http.Server{
    Addr:      fmt.Sprintf(":%d", config.ServerInfo.HttpsPort),
    Handler:   mux,
    TLSConfig: tlsConfig,
}
srv.ListenAndServeTLS(config.AppInfo.Scheme.CertFile, config.AppInfo.Scheme.KeyFile)

```

If `Https` is `false` or the `CertFile` and `KeyFile` entries are empty, CasaOS starts a plain HTTP server instead, as implemented in [`main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go).

## Step-by-Step HTTPS Configuration

### Enable HTTPS in casaos.conf

To configure CasaOS with certificate and key files:

1. Edit [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf) and locate the `[scheme]` section
2. Set `Https = true` to enable TLS mode
3. Specify absolute paths for `CertFile` and `KeyFile` pointing to valid PEM files
4. Restart the CasaOS service to apply the changes

### Example Configuration

Minimal `[scheme]` section for [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf):

```ini
[scheme]
Https = true
CertFile = /etc/casaos/ssl/casaos.crt
KeyFile = /etc/casaos/ssl/casaos.key

```

The `conf/casaos.conf.sample` file in the repository provides a template for adding this section.

### Programmatic TLS Check

The server initialization code checks the `Https` flag before deciding between TLS and plain HTTP:

```go
if config.AppInfo.Scheme.Https {
    err = srv.ListenAndServeTLS(
        config.AppInfo.Scheme.CertFile,
        config.AppInfo.Scheme.KeyFile,
    )
} else {
    err = srv.Serve(listener)
}
if err != nil && err != http.ErrServerClosed {
    log.Fatalf("server error: %v", err)
}

```

## Summary

- The `Scheme` struct in [`internal/conf/config.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/internal/conf/config.go) defines the HTTPS configuration model with `Https`, `CertFile`, and `KeyFile` fields
- Configuration values are loaded from [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf) via the `InitSetup` function in [`pkg/config/init.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/config/init.go)
- When enabled, CasaOS passes certificate paths to `ListenAndServeTLS` using Go's standard library TLS implementation
- HTTPS requires valid PEM-encoded certificate and key files with absolute paths specified in the `[scheme]` section
- If certificate paths are missing or invalid while `Https` is enabled, the server will fail to start

## Frequently Asked Questions

### Where does CasaOS store its HTTPS configuration?

CasaOS stores HTTPS settings in the [`/etc/casaos/casaos.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf) file under the `[scheme]` section. This INI-formatted file maps to the `Scheme` struct defined in [`internal/conf/config.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/internal/conf/config.go), containing the `Https` boolean flag and paths for `CertFile` and `KeyFile`.

### What file format does CasaOS expect for SSL certificates?

CasaOS expects PEM-encoded certificate and key files. The `CertFile` path should point to a PEM-encoded TLS certificate, while `KeyFile` should point to the matching unencrypted private key. The system passes these paths directly to Go's `ListenAndServeTLS` function.

### Does CasaOS support automatic HTTPS certificate generation?

No, according to the source code analysis, CasaOS does not implement automatic certificate generation. Administrators must provide pre-existing certificate files and specify their paths in the configuration file. The system only reads existing files via the standard `ListenAndServeTLS` implementation.

### What happens if the certificate files are missing or invalid?

If `Https` is set to `true` but the certificate files are missing, invalid, or the paths are incorrect, the `ListenAndServeTLS` call will fail and CasaOS will log a fatal error during startup. If `Https` is `false` or the paths are empty, CasaOS starts a plain HTTP server instead.