Customize Companion Hub compose and traefik config

In this guide, we’ll show you how to customize the default Docker Compose file of Companion Hub and the traefik config.

The user compose override file is hub-compose.yml. Hub still reads the legacy name tipi-compose.yml if hub-compose.yml is absent, so existing setups keep working — but use hub-compose.yml for anything new.

This guide is for advanced users who are familiar with Docker and traefik. If you break the config we won’t be able to help you. You will probably face issues if the main Companion Hub config is changed.

Example use cases

Enable the traefik dashboard
Change the log level of traefik to DEBUG

Create a custom Docker Compose file

In this example we will expose the traefik dashboard by editing the main Companion Hub compose file.

Firstly we need to figure out what port traefik dashboard uses (which is 8080) and what is the name of the Docker container of traefik (which we can learn from the docker-compose.yml) which is traefik in this case.

Don’t edit the docker-compose.yml file directly because it will be overwritten on every restart of Companion Hub.

Create the custom Docker Compose file

Create the file hub-compose.yml in the user-config directory inside your Hub data root (ROOT_FOLDER_HOST):


nano "$ROOT_FOLDER_HOST/user-config/hub-compose.yml"

Not sure where your data root is? Run cihub status, or see Folder Structure.

Add your changes

For this example add the following contents:


services:
  traefik:
    ports:
      - 8080:8080

Then save and exit.

Check your file structure

You should have this file structure:

- - hub-compose.yml

Restart Companion Hub and test the changes


cihub down && cihub up prod --detached

After restarting you should be able to see the traefik dashboard by visiting SERVER-IP:8080

Edit the traefik config file

In this example we will just change the log level of traefik to DEBUG, that is a very simple example to showcase the process.

Firstly we need to figure out what we need to change, the default traefik config of Companion Hub is this:


api:
  dashboard: true
  insecure: true
 
providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    watch: true
    exposedByDefault: false
  file:
    directory: /root/.config/dynamic
    watch: true
 
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: myresolver
 
certificatesResolvers:
  myresolver:
    acme:
      email: acme@thisprops.com
      storage: /shared/acme.json
      httpChallenge:
        entryPoint: web
 
log:
  level: ERROR

We can see that the part we need to change is this:


log:
  level: ERROR

By default if you try to edit the traefik config it will be overwritten on every restart. To keep the config we need to change a setting which can be done easily by editing the settings.json file.

Modify the the settings

Open the state/settings.json file inside your Hub data root (ROOT_FOLDER_HOST) with your preferred editor. Your settings file will look something like this:


{
  "dnsIp": "9.9.9.9",
  "internalIp": "10.10.10.5",
  "postgresPort": 5432,
  "appsRepoUrl": "https://github.com/your-org/your-app-store",
  "domain": "example.com",
  "appDataPath": "/home/user/companion-hub/",
  "localDomain": "ci.lan",
  "demoMode": false,
  "guestDashboard": false,
  "allowAutoThemes": true,
  "allowErrorMonitoring": true,
  "persistTraefikConfig": false
}

Here you need to change the "persistTraefikConfig" from false to true.

Now Companion Hub will keep your custom traefik config on start, you can always change it back to false to reset your changes. So now that our config is persistent we can safely make our changes by opening the traefik/traefik.yml file and changing this:


log:
  level: ERROR

To this:


log:
  level: DEBUG

Test the changes

Finally restart Companion Hub:


cihub restart

Congratulations! Now your traefik container will run in debug mode so you can fix some problem for example.