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

CasaOS enables HTTPS by reading the CertFile and KeyFile paths from the [scheme] section of /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, 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, 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 loads the configuration file using ini.Load() and maps the [scheme] section to the global configuration object.

// 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.

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.

Step-by-Step HTTPS Configuration

Enable HTTPS in casaos.conf

To configure CasaOS with certificate and key files:

1. Edit /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:

[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:

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 defines the HTTPS configuration model with Https, CertFile, and KeyFile fields
• Configuration values are loaded from /etc/casaos/casaos.conf via the InitSetup function in 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 file under the [scheme] section. This INI-formatted file maps to the Scheme struct defined in 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.

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