Docker Image

Docker Hub

Docker images for the CoolerControl daemon coolercontrold are available from the official Docker Hub repository.

Quick Start

Run the container with the minimum required options:

docker run -d \
  --name coolercontrold \
  --restart unless-stopped \
  --privileged \
  -p 11987:11987 \
  -v /path/to/config:/etc/coolercontrol \
  coolercontrol/coolercontrold

Once started, open http://<host-ip>:11987/ in your browser to access the Web UI.

TIP

The Docker image sets CC_TLS=OFF and binds to all interfaces (0.0.0.0 / ::) by default, so the Web UI is accessible over plain HTTP without additional network configuration.

Privileged Mode

Running with --privileged gives the container full access to host hardware, which is the easiest way to get started. It allows CoolerControl to discover all available devices on the system.

WARNING

It is not recommended to leave the container in privileged mode long-term. After initial device discovery, you should pass through only the specific devices and paths needed. See Device Access below.

Docker Compose

services:
  coolercontrold:
    image: coolercontrol/coolercontrold
    container_name: coolercontrold
    restart: unless-stopped
    privileged: true
    ports:
      - "11987:11987"
    volumes:
      - ./coolercontrol-config:/etc/coolercontrol

Start with:

docker compose up -d

Environment Variables

The Docker image sets the following defaults, which differ from a native installation:

Variable	Default (Docker)	Description
CC_PORT	11987	HTTP/HTTPS port
CC_HOST_IP4	0.0.0.0	IPv4 bind address (all interfaces)
CC_HOST_IP6	::	IPv6 bind address (all interfaces)
CC_TLS	OFF	TLS disabled by default in Docker
CC_DBUS	OFF	D-Bus integration disabled
CC_SERVICE_MANAGER	OFF	Plugin Service manager integration disabled

Override any variable with -e or in the environment section of your Compose file:

docker run -d \
  --name coolercontrold \
  -e CC_PORT=8080 \
  -p 8080:8080 \
  -v /path/to/config:/etc/coolercontrol \
  coolercontrol/coolercontrold

Accessing the Web UI

Because the Docker image defaults to CC_TLS=OFF and binds to all interfaces, the Web UI is available at:

http://<host-ip>:11987/

Device Access

CoolerControl needs access to hardware sensors and controllable devices on the host. There are two approaches:

hwmon (Sensors and Fan Control)

The /sys/class/hwmon mount provides access to hardware monitoring sensors.

-v /sys/class/hwmon:/sys/class/hwmon

To enable fan control through hwmon without privileged mode, mount the specific hwmon device directory with read-write access. Find the correct path by checking the device locations in the CoolerControl Web UI under Device Details:

-v /sys/class/hwmon:/sys/class/hwmon:ro \
-v /sys/devices/platform/it87.2608/hwmon/hwmon3:/sys/devices/platform/it87.2608/hwmon/hwmon3

USB Devices (AIOs, Fan Hubs, LED Controllers)

USB devices such as AIOs, fan hubs, and LED controllers appear under /dev/hidraw*. Pass them through with --device:

--device /dev/hidraw0
--device /dev/hidraw1

Check which devices CoolerControl discovers by opening Device Details in the Web UI and looking at the Locations field.

Recommended Workflow

1. Start the container in privileged mode for initial device discovery
2. Open the Web UI and check Device Details for each device to find its location paths
3. Add the required -v mounts and --device flags to your container configuration
4. Disable privileged mode and restart the container
5. Verify all devices still appear and fan control works

Persistent Configuration

Mount a host directory or Docker volume to /etc/coolercontrol to persist your configuration across container restarts and upgrades:

-v /path/to/config:/etc/coolercontrol

This directory stores the daemon's config.toml, device settings, and any custom TLS certificates.

Enabling TLS in Docker

If you expose the Web UI over an external network (not just localhost), you should enable TLS to encrypt traffic and protect any configured access credentials.

To enable TLS, mount your certificate and key files into the container and set the appropriate environment variables:

docker run -d \
  --name coolercontrold \
  -e CC_TLS=ON \
  -e CC_CERT_PATH=/etc/coolercontrol/cert.pem \
  -e CC_KEY_PATH=/etc/coolercontrol/key.pem \
  -p 11987:11987 \
  -v /path/to/config:/etc/coolercontrol \
  -v /path/to/cert.pem:/etc/coolercontrol/cert.pem:ro \
  -v /path/to/key.pem:/etc/coolercontrol/key.pem:ro \
  -v /sys/class/hwmon:/sys/class/hwmon:ro \
  coolercontrol/coolercontrold

With TLS enabled, the Web UI is accessible at https://<host-ip>:11987/. See the SSL/TLS documentation for certificate options including Let's Encrypt.

See Also

• Unraid - Detailed Unraid-specific setup guide
• Access Protection - Set a password for the Web UI
• Remote Access - Remote access configuration and best practices
• SSL/TLS - TLS encryption options
• TCP Port and Address - Port and address configuration details