en.Installation LXC

If you want to run OpenCCU as a native, lightweight Linux container on an existing Debian-based host (Debian, Ubuntu, Raspberry Pi OS, Armbian, …), you can do this with Linux Containers (LXC). The following steps guide you through a semi-automated installation of an OpenCCU LXC system.

• A Debian-based amd64 or arm64 host system (32-bit systems are no longer supported since OpenCCU 3.87.6.20260313).
• For the container: at least 1 GB, recommended 2 GB of RAM as well as 2 CPU cores.
• The pivccu-modules-dkms kernel modules installed by the script must be at least version 1.0.88; for older installations, update them via sudo apt update && sudo apt install --only-upgrade pivccu-modules-dkms if necessary.
• A supported radio module.

To run an OpenCCU LXC container reliably, the host must first be prepared correctly in terms of networking. OpenCCU expects a bridge (br0) with a static IP address on the host, through which the host is connected to the LAN. The setup differs depending on the distribution and network stack.

The following placeholders in angle brackets <…> are used below:

• <device>: name of the primary network interface (e.g. eth0) of the host.
• <address>/<prefix>: static IPv4 address with network prefix (e.g. 192.168.178.10/24).
• <gateway>: IPv4 address of the default gateway/router (e.g. 192.168.178.1).
• <dns1>,<dns2>: IPv4 address(es) of the DNS server(s) (e.g. 192.168.178.1).

If you use NetworkManager (e.g. on Armbian, Raspberry Pi OS), set up the bridge as follows:

1. Determine the active interface

   nmcli con show --active

   Note the primary interface (e.g. eth0) as well as the future static IP (incl. prefix).

2. Install bridge-utils

   sudo apt install bridge-utils

3. Create and configure the bridge

   sudo nmcli con add type bridge ifname br0 con-name br0 stp no forward-delay 0
   sudo nmcli con add type bridge-slave ifname <device> master br0
   sudo nmcli con modify br0 ipv4.addresses "<address>/<prefix>" ipv4.gateway "<gateway>" ipv4.dns "<dns1>,<dns2>" ipv4.method manual

   Caution: During the reconfiguration, the network connection may drop briefly. For remote access, have a console/monitor ready if necessary.

4. Restart Check the bridge with ip a or nmcli. Then perform a restart to be on the safe side:

   sudo reboot

On systems with ifupdown (e.g. classic Debian):

1. Install bridge-utils

   sudo apt install bridge-utils

2. Adjust /etc/network/interfaces

   auto lo
   iface lo inet loopback
   
   iface <device> inet manual
   
   auto br0
   iface br0 inet static
       address <address>/<prefix>
       gateway <gateway>
       dns-nameservers <dns1>,<dns2>
       bridge_ports <device>
       bridge_stp off
       bridge_fd 0
   

3. Restart

   sudo reboot

On systems with netplan (e.g. Ubuntu):

1. Adjust /etc/netplan/<file>.yaml

   network:
     version: 2
     renderer: networkd
   
     ethernets:
       <device>:
         dhcp4: no
         dhcp6: no
   
     bridges:
       br0:
         dhcp4: no
         dhcp6: no
         interfaces: [<device>]
         addresses: [<address>/<prefix>]
         routes:
           - to: default
             via: <gateway>
         nameservers:
           addresses: [<dns1>, <dns2>]
         parameters:
           stp: false
           forward-delay: 0

2. Apply the changes

   sudo netplan generate
   sudo netplan --debug apply

   Caution: Here, too, the connection may drop briefly. In case of a misconfiguration, use a local console if necessary.

3. Restart

   sudo reboot

Once the requirements are met and the br0 bridge is active, the OpenCCU container can be installed as follows:

1. Start the installation script Run the downloader in a shell (locally or via SSH):

   sudo sh -c "wget -qO - https://openccu.de/install-lxc.sh | bash -"

2. Confirm the dependency check The script checks the required packages and host modifications and shows an information dialog. Confirm with Yes to continue.
   

   Note: The changes made by the script can be undone at any time; see section Uninstallation (uninstall option).

3. Radio module overlays (ARM/GPIO only) On ARM hosts with a GPIO radio module (RPI-RF-MOD / HM-MOD-RPI-PCB), the script asks whether the required device tree overlays should be installed.
   

   Note: With a USB (HmIP-RFUSB, HB-RF-USB-2, …) or Ethernet connection (HB-RF-ETH), no overlay installation is necessary → select No.

4. Select the version Select the desired OpenCCU version (release or snapshot).
   

   Recommendation: For productive use, prefer release versions; snapshots are experimental.

5. Define the userdisk path Enter the path for the "userdisk" (persistent data), default: /var/lib/openccu/userfs.
   

   Caution: An already used userfs must not be used by several containers at the same time.

6. Define the container name Assign a unique name to the OpenCCU container.
   

7. Assign CPU cores Select the number of CPU cores (recommended ≥ 2).
   

8. Limit the memory Define the RAM limit for the container (minimum 1024 MB, default 2048 MB).
   

9. Perform the installation The script creates and configures the container.
   

10. Restart (if overlays/modules were installed)

    sudo reboot

After the reboot, the host starts again; ideally, the new OpenCCU LXC is started directly. View the console: lxc-console <name>; enter a shell: lxc-attach <name>. Further information can be found in the script output and in the official LXC man pages. The WebUI is then accessible at http://openccu/ or the IP address of the container; afterwards, the first steps after installation help with the further setup.

To update an existing OpenCCU LXC:

1. Stop the container

   lxc-stop <name>

2. Create a backup/snapshot

   lxc-snapshot <name>

3. Start the update script

   sudo sh -c "wget -qO - https://openccu.de/install-lxc.sh | bash -s update"

   

4. Select the container

5. Select the target version

   Note: For productive systems, select release instead of snapshot.

6. Confirm the update

7. Update running/completed

Finally, start the container again:

lxc-start <name>

To follow the boot output:

lxc-console <name>

Since host modifications were made for LXC operation (packages, modules, overlays), you can remove them again with the uninstall option of the script:

1. Start the uninstallation

   sudo sh -c "wget -qO - https://openccu.de/install-lxc.sh | bash -s uninstall"

2. Confirm

3. Let the removal be performed

   Note: In case of error messages, run the process again if necessary; the script checks before each step whether the respective component still exists.

The OpenCCU container itself and its userdisk are not removed in the process. If desired, delete the container with sudo lxc-destroy <name> and remove the userdisk directory (default: /var/lib/openccu/userfs) manually.

After a successful uninstallation, plan a restart. Dependencies that are no longer needed can optionally be removed via

sudo apt autoremove