Addons.cfg and first run config

I’m trying to use the addons.cfg file in the services folder as a base configuration for my OpenHAB setup as I experiment and destroy and recreate containers.

It says at the top of the file

# The installation package of this openHAB instance
# Note: This is only regarded at the VERY FIRST START of openHAB

But when I restart the container it will read this file every time and overwrite any changes such as removing or adding bindings.

Is there something different about a Docker setup that makes this not work?

Also, can I make a .cfg file in the services folder for every binding? Some are created automatically.
Can I make a cgf file to set the logging pattern in userdata/etc/log4j2.xml, and config files I find in /userdata/config/org/openhab for example?

I moved this to a more appropriate category. The tutorials and solutions category is a place to post tutorials and solutions, not a place to ask for them.

No, it’s working as designed. addons.cfg will take precedence over everything. Once you start using addons.cfg to install add-ons, you must use it for all your installed add-ons. If you try to install an add-on through the UI later, it will become uninstalled because it’s not listed in addons.cfg.

Theoretically yes, you should be able to make most config changes through cfg files in $OH_CONF/services. However, you have to have a lot of internal knowledge about class names and stuff which you’ll mainly only be able to find out by studying the code.

I’m pretty certain you cannot configure the logging from this folder. You have to use the userdata/etc/log4j2.xml file of the karaf console (which in turn modifies this file).

But one might ask, why not use the $OH_USERDATA files themselves? Everything in $OH_CONF/services gets translated to files in $OH_USERDATA/config. So why not keep a copy of those files as the base for your containers instead? And if you do that, any changes you make through the UI will stick instead of becoming overwritten when addons.cfg is reloaded.

Thanks for your answer.

The text in addons.cfg is either wrong or very misleading in that case.
It says it will only run once, which you are saying is not true, and confirmed by my experience.

I will use the userdata folders once created, but unless the folder is empty and/or completely deleted, the Docker container wont recreate any missing files to create a fresh install. I am trying to create a clean install process that isn’t just a backup of the mess I made earlier, and to make it quicker to redeploy on my various pis etc.
I have a personal GitHub repo of my base system, but including userdata makes it not work as smoothly as it could, and it is more likely that I will mess it up when managing all the git pulls and pushes etc.
I want to install a bunch of preconfigured bindings, databases, and other items in the OpenHAB app store (what are we calling it?) etc. that I can then go wild on again.

I want to edit the log.config because I don’t want the logs truncated as I am reading and filtering them with Grafana.

I use the items and rules files to hold those items, but I will be looking for a good way to backup and redeploy widgets and pages as part of this endeavor which only live in the userdata folder.

I don’t think there is much else needed to make a replica-but-actually-a-fresh-install of my entire system just by creating/recreating the Docker container.

The steps should be:

  1. Clone my personal repo to a Pi which includes my docker compose file and all the folders needed for my persistent data for all software in the stack.
  2. Start docker compose file which recreates all the missing folders.

I know I can make it work by including the userdata folder, but without would be better.

I think the “VERY FIRST START” is referring to when OH starts up as opposed to whenever the file is changed which is different from most of the other files in $OH_CONF.

If you are using addons.cfg, you are not creating a clean install. You are creating a preconfigured install.

The Marketplace. I don’t think that addons.cfg supports installs from the Marketplace yet but I’ve seen PRs and issues on core to add support for that.

But as has always been the case with OH all the way back to 2.0, if you use addons.cfg, you can only use addons.cfg. You can’t mix and match between using that file and the UI/Karaf console to manage your addons.

So if you want to have a clean install and still be able to manage stuff through the UI, you have to do it by adding $OH_USERDATA to your git. There are a couple of folders you should exclude like cache and tmp and maybe persistence. Or if you don’t want to do that, you can’t use the UI and have to only use addons.cfg.

I’m not sure how $OH_USERDATA is any more difficult to manage than $OH_CONF in git. You have all the same issues with branches and such.

You can’t get there from here unless you:

  • only manage add-ons through addons.cfg
  • only manage Things, Items, and Rules through text configs in $OH_CONF
  • only manage the configuration of add-ons through cfg files in $OH_CONF and never in the UI
  • don’t use any configuration of MainUI at all (that’s only stored in $OH_USERDATA)
  • don’t make any changes to the logging config or other configs that live in $OH_USERDATA (e.g. user/passwords for the karaf console, UID and secret for the openHAB Cloud Connector, etc.)

Since that’s pretty much impossible you will have to include at least parts of $OH_USERDATA.

But I’m not sure how I see that as any different in meeting your goals.

  1. Check in your “base” config and tag it or keep it on its own branch.
  2. When spinning up a new OH instance, check out that tag to the mounted volume(s).
  3. Switch to a new branch to capture your new experiments.

Whether you are using only $OH_CONF or $OH_USERDATA the steps are the same.


I think I will probably include userdata based on everything you have said

In case it helps, here’s my .gitignore. I have everything in one repo and mount addons, conf, and userdata folders to the appropriate places in the container. The userdata stuff is probably the most relevant. But you can see I exclude all of userdata and then override only those folders that are relevant to be saved to git.


When you upgrade the version of OH, you’ll probably want to rebaseline your starting branch because some of the files in $OH_USERDATA/etc might be changed during the upgrade process. There will be an upgrade log file generated with all the files modified.

1 Like

Thank you, it does help