Customize Companion Home compose and traefik config

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

The user compose override file is currently named tipi-compose.yml for legacy reasons. This will be renamed in a future release.

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

Create the custom Docker Compose file

Create the file tipi-compose.yml in the user-config directory within the cihome folder:


nano user-config/tipi-compose.yml

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:

- - tipi-compose.yml

Restart Companion Home and test the changes


docker compose restart

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 Home 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 cihome/state/settings.json file with your prefered 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/cihome/",
  "localDomain": "tipi.lan",
  "demoMode": false,
  "guestDashboard": false,
  "allowAutoThemes": true,
  "allowErrorMonitoring": true,
  "persistTraefikConfig": false
}

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

Now Companion Home 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 Home:


sudo docker compose restart

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