Being neither overly familiar with Linux systems nor with git, I always wanted a versioning workflow for my (text based) openHAB config, but couldn’t find an easy to follow guide. Now I finally found the time to get to know git a bit better (see source) and decided to share my results with you.
What do I try to archive:
- file versioning
- keeping more than one up to date copy of my config files
- no coding on my openHAB server
- no cloud server involved
- keeping the workflow as hassle free and as easy to use as possible
What I’m not aspiring to:
This is not a fully fledged backup solution, for that you should look at Amanda
Main Source
For git related steps I will reference Pro Git throughout this post. If you are unfamiliar with git or want to deepen your understanding, it would not hurt to read the whole book, but you can follow this post without doing so.
Setup
- openHAB server (openHABianPi on Raspi 3, paths used in this post might vary on different setups)
- text / file based openHAB 2 configuration
- main computer (Mac-/Windows-Client)
Installation
Both platforms: To check if git is already installed, run the following command in your shell / Terminal / PowerShell:
git --version
OpenHABianPi does already come with a git installation, if your platform is missing git, have a look at Pro Git, Installation.
Initialization
Both plattforms: You might want to configure git and at least to set your credentials.
$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com
Additional explanations / options see Pro Git, First Time Git Setup
openHAB: Initialize a git repository in your config folder and stage & commit your existing files.
Optional: Additionally I create a .gitignore file, telling git to ignore temporary files, see also Pro Git, Recording Changes to the Repository, Section Ignoring Files:
$ cd /etc/openhab2/
$ git init
$ echo '*~' > .gitignore
$ git commit -a -m "<Initial Commit>"
Cloning
main computer: Now we create a new repository on our main computer as a copy of our openHAB repo.
So fire up your Terminal / PowerShell, navigate to a folder of your choice and use the following command:
$ git clone ssh://openhabian@openHABianPi/etc/openhab2/ --origin openHABianPi config
Explanation:
- openhabian: A user with write / read permissions in your config folder on your openHAB server
- openHABianPi: The DNS name of your openHAB server, you could use the IP address instead
- /etc/openhab2/: Path to your config folder on your openHAB server
- –origin openHABianPi: Name for the remote repo, used for push/pull commands in the future. If you omit this, the remote repo will get the default name ‘origin’
- config: Folder name for the repo on your main machine
After you send the command, you might be asked for the password of specified user and a new folder called ‘config’ will be created in the location of your choice, containing a copy of your openHAB repo.
Optional: SSH Keys
Avoiding password request for every ssh connection / push / pull / …
main computer: Follow Pro Git, Generating Your SSH Public Key
openHAB:
A second method is to create a single git user account on the machine, ask every user who is to have write access to send you an SSH public key, and add that key to the ~/.ssh/authorized_keys file of that new git account. At that point, everyone will be able to access that machine via the git account. This doesn’t affect the commit data in any way — the SSH user you connect as doesn’t affect the commits you’ve recorded.
(From Pro Git, Getting Git on a Server)
The single git account would be a user with write / read permissions in your config folder on your openHAB server (for example openhabian on openHABianPi setups), the public key is the key you just generated on you main computer.
Push to Deploy
main computer: If we now change stuff in our working repo, commit this stuff and want to push it to our openHAB repo, we will get an error message:
$ cd /path/to/working/repo
$ cd config/rules
$ vim example.rules
$ git commit -a -m "Did some changes to example.rules"
$ git push
The reason for the error message is, that git isn’t happy with pushes to non-bare repositories - reasons / details see here.
openHAB: To change that we have to set a flag in our openHAB repo:
$ cd /etc/openhab2/
$ git config --local receive.denyCurrentBranch updateInstead
Now your openHAB repo will accept pushed changes and will update the content of your config folder accordingly.
This can lead to trouble and lost changes if you have non-committed changes in your openHAB repo. If you set this flag change files only anymore in your working repo!
Remark: If you don’t want to push to deploy, you have to make the working repo available as remote repo in your openHAB repo and to pull, merge and checkout changes manually.
Finished
Now you don’t have to touch your openHAB server anymore to change your config, you just make your changes in your working repo, commit them and than push the change to your openHAB repo:
main computer
$ cd /path/to/working/repo
$ cd config/rules
$ vim example.rules
$ git commit -a -m "Did some changes to example.rules"
$ git push
Additional Options:
- I’m using now my own git server as describted here: Setting up my own git server on a pi
- VS Code, the supported editor for openHAB config files, does support git, meaning that you can push / pull changes directly in the editor without using a shell / Terminal / PowerShell.
- put your working repo inside your Dropbox folder to have it available on more than one computer without using a cloud git server
- Use a cloud git server if you don‘t care about an local workflow / if you want to publish your config (gitignore/encrypt sensitive files (e.g. files containing passwords)!)
- A way to organize your repo with branches if you have more than one openHAB server
- Use git for more than only your config folder (for example your userdata folder) you can either create more than on repo, or use symlinks to use only one repo (inspired by @rlkoshak). If you prefere the second option, you have to move the folders into your git folder and create the symlinks in the original location (git doesn’t follow symlinks):
sudo systemctl stop openhab2.service
sudo mkdir /home/openhabian/git
sudo mkdir /home/openhabian/git/config
sudo mkdir /home/openhabian/git/userdata
sudo mv /etc/openhab2/* /etc/openhab2/.* /home/openhabian/git/config/
sudo mv /var/lib/openhab2/* /var/lib/openhab2/.* /home/openhabian/git/userdata/
sudo rm -r /etc/openhab2/
sudo rm -r /var/lib/openhab2/
sudo ln -s /home/openhabian/git/config /etc/openhab2
sudo ln -s /home/openhabian/git/userdata /var/lib/openhab2
sudo chown -R openhabian /home/openhabian/git/
sudo systemctl start openhab2.service
EDIT: Be wary - at least in my case moving /var/lib/openhab2/ into my git repo caused so many permission based problems that I have to do a fresh openHAB installation.
EDIT: Added link ‘A way to organize your repo with branches if you have more than one openHAB server’
Questions
- Which folders, other than config & userdata, might also be of interest for versioning?
Please let me know when you find mistakes / see ways to improve this post.
) prompted to type in the password of my openhabian user on the openHAB server. Once typed in everything works as expected.