en.Installation Docker OCI - jens-maus/RaspberryMatic GitHub Wiki

Since version 3.55.10, it is possible to run RaspberryMatic also as a docker/OCI container on existing amd64, aarch64/arm64 or arm-based systems. While the docker version comes with almost all functionality that a "normal" RaspberryMatic system provides, some functionality like, e.g. the network setup or WebUI-based update mechanism has been explicitly disabled since these operations are usually performed on the system hosting the docker container itself rather than within the container.

Furthermore, while almost the same hardware requirements in terms of homematic rf-modules apply like with a standard RaspberryMatic system, the kernel drivers for, e.g. the RPI-RF-MOD or HM-MOD-RPI-PCB as well as for the HB-RF-USB/HB-RF-USB-2 and the HB-RF-ETH have to be installed on the hosting machine rather than within the container. The container then just uses these preloaded kernel drivers. This driver installation can be either performed using a dedicated deploy.sh installation script or manually. In either cases, kernel modules are installed that are kindly developed and distributed by the author of piVCCU (@alexreinert).

Debian/Ubuntu-based Host system

Prerequisites (on host system):

Ensure you installed docker:
```
sudo apt install docker
```
Make sure to add the user under which the docker should run to the docker group:
```
sudo usermod -aG docker $USER
```
Make sure the docker environment works correctly by executing the hello-world example docker:
```
docker run hello-world
```

Install pivccu-modules-dkms kernel modules (required for RPI-RF-MOD/HM-MOD-RPI-PCB use):

wget -qO - https://apt.pivccu.de/piVCCU/public.key | sudo gpg --dearmor -o /usr/share/keyrings/pivccu-archive-keyring.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/pivccu-archive-keyring.gpg] https://apt.pivccu.de/piVCCU stable main" >/etc/apt/sources.list.d/pivccu.list'
sudo apt update
sudo apt install build-essential bison flex libssl-dev
sudo apt install pivccu-modules-dkms

Install eq3_char_loop kernel module to automatic module load section:

sudo sh -c 'echo eq3_char_loop >/etc/modules-load.d/eq3_char_loop.conf'

Start+Load all necessary kernel modules on host:

sudo service pivccu-dkms start
sudo modprobe eq3_char_loop

RaspberryMatic Docker Installation

Using `deploy.sh` script:

Warning: Please note that the current version of the deploy.sh script directly applies changes to the host system where the docker container is started, thus care should be taken when executing it via sudo/root rights.

Download deploy.sh:

wget https://raw.githubusercontent.com/jens-maus/RaspberryMatic/master/buildroot-external/board/oci/deploy.sh
chmod 755 deploy.sh

Execute the script:
```
./deploy.sh
```
- the script will install all dependencies (including pivccu-modules-dkms) on first run.
- the script will start the container in daemon mode with default settings

Using `docker pull`:

Use docker pull to retrieve the latest version:

docker pull ghcr.io/jens-maus/raspberrymatic:latest

Run the raspberrymatic docker using cmd-line:

docker run --tty --interactive --name ccu --volume=ccu_data:/usr/local \
           --publish=8080:80 --privileged --restart=always --stop-timeout=30 \
           --hostname homematic-raspi ghcr.io/jens-maus/raspberrymatic:latest

Using `docker load`:

Download the latest docker/oci image version of RaspberryMatic:

wget https://github.com/jens-maus/RaspberryMatic/releases/download/3.XX.XX.YYYYMMDD/RaspberryMatic-3.XX.XX.YYYYMMDD-oci_amd64.tgz

Use docker load to load the downloaded into the docker environment:
```
docker load < RaspberryMatic-3.XX.XX.YYYYMMDD-oci_amd64.tgz
```

Run the raspberrymatic docker using cmd-line:

docker run --tty --interactive --name ccu --volume=ccu_data:/usr/local \
           --publish=8080:80 --privileged --restart=always --stop-timeout=30 \
           --hostname homematic-raspi raspberrymatic:amd64-latest

Using `docker compose`

Add the following to your docker-compose.yml:

services:
  raspberrymatic:
    image: ghcr.io/jens-maus/raspberrymatic:latest
    container_name: ccu
    hostname: homematic-raspi
    privileged: true
    volumes:
      - ccu_data:/usr/local
    ports:
      - "8080:80"
      - "2001:2001"
      - "2010:2010"
      - "9292:9292"
      - "8181:8181"
    restart: unless-stopped
    stop_grace_period: 30s

Start your docker compose environment:
```
docker-compose up -d
```

WebUI access to container

After startup, point your web browser to the IP of your hosting system and with port :8080 and you should see the usual CCU WebUI:

http://<IP>:8080/

Migration from angelnu/ccu

If you come from angelnu docker CCU you can update following the same install instructions as above. Your data will be preserved. If you previously changed the default data volume or container name please see the additional settings below to adjust.

Update to newer versions

The RaspberryMatic docker has to be updated from the host machine (the recommended "docker way"). Use either the same instructions like in using deploy.sh and the other subsections (e.g. using docker pull) so that you retrieve the very latest version of the RaspberryMatic docker with the next execution.

Additional `deploy.sh` settings

You can pass variables to change the defaults in the script:

CCU_REGA_HTTPS_PORT
- HTTPS port -> mapped to port 443 in container
- Default: 8443
CCU_REGA_HTTP_PORT
- HTTP port -> mapped to port 80 in container
- Default: 8080
CCU_SSH_PORT
- SSH port -> mapped to port 22 in container
- Default: 2222
CCU_PORTS_TO_OPEN
- Additional ports to open
- Default: "2001 2010 8181"
CCU_DATA_VOLUMEN
- Name of the docker volume where CCU data will persist. It can be a local location as well such as a mounted NAS folder, cluster fs (glusterfs), etc.
- Default: "ccu_data"
CCU_OCI_REPO
- Container repository to use
- Default: "ghcr.io/jens-maus/raspberrymatic"
CCU_OCI_TAG
- Container image tag to use
- Default: "latest"
CCU_OCI_TAG
- Name of the container instance (by default uses same as angelnu/ccu for easier migration)
- Default: "ccu"
CCU_DOCKER_OPTIONS
- Additional options for docker run
- Default: ""
CCU_DOCKER_STOP_TIMEOUT
- time allowed to stop the container before Docker kills it
- Default: 30 (seconds)

Docker on WSL

TBD - It should be able to follow the above instructions