Configuration Backup to GitHub

Backing up and regularly syncing your Open Peer Power configuration to GitHub has several benefits:

• A remote copy of your Open Peer Power YAML files in case you need to recover.
• A documented history of your changes for troubleshooting purposes.
• It will help the Open Peer Power community learn from your configuration examples.

Important Best Practices

Some best practices to consider before putting your configuration on GitHub:

• Extensive use of secrets.yaml to hide sensitive information like usernames, passwords, device information, and location.
• Exclusion of some files, including secrets.yaml and device-specific information using a .gitignore file.
• Regularly committing your configuration to GitHub to make sure that your backup is up to date.
• Use a README.md to document your configuration and include screenshots of your Open Peer Power frontend.

Step 1: Installing and Initializing Git

In order to put your configuration on GitHub, you must install the Git package on your Open Peer Power server (instructions below will work on Raspberry Pi, Ubuntu or any Debian-based system) Note: this isn’t required in Opp.io, it’s included as default so proceed to step 2:

sudo apt-get update
sudo apt-get install git

Step 2: Creating .gitignore

Creating a .gitignore file in your repository will tell Git which files NOT to push to the GitHub server. This should be used to prevent publishing sensitive files to the public. It should contain a list of filenames and pattern matches. This list should include at least your secrets.yaml file, device configuration files, and the Open Peer Power database/directory structure. The .gitignore file should be placed in the root of your Open Peer Power configuration directory: <config dir>/.gitignore.

Here is an example that will ignore everything but your YAML configuration.

# Example .gitignore file for your config dir.
# An * ensures that everything will be ignored.
*

# You can whitelist files/folders with !, these will not be ignored.
!*.yaml
!.gitignore
!*.md

# Ignore folders.
.storage
.cloud
.google.token

# Ensure these YAML files are ignored, otherwise your secret data/credentials will leak.
ip_bans.yaml
secrets.yaml
known_devices.yaml

More information on the layout of the file can be found in the .gitignore manual.

Step 3: Preparing your Open Peer Power directory for GitHub

In your Open Peer Power directory, type the following commands as the Open Peer Power user, replacing the email address and name with your information:

git init
git config user.email "you@example.com"
git config user.name "Your Name"
git add .
git commit

After the git commit command, you will be asked to enter a message for the commit. This will add a comment beside each file on GitHub describing the purpose for the commit. In this case, you can enter something like “Initial commit of my Open Peer Power configuration”. To exit the editor, press CTRL + C and then :wq which will exit and save the changes.

Step 4: Creating Repository on GitHub

• Connect to GitHub and login to your account (or create an account if you don’t already have one).
• Click “New Repository” and give your repository a name/description (Open-Peer-PowerConfig is used in the example below). You do NOT need to change any other options.
• Click “Create Repository”

Step 5: Your initial commit to GitHub

Once you are sure you are using secrets.yaml and .gitignore correctly, it is time to push your configuration to the GitHub Repository that you just created.

In your Open Peer Power directory, type the following commands as the Open Peer Power user, replacing “username” in the URL with your GitHub username:

git remote add origin https://github.com/username/Open-Peer-PowerConfig
git push -u origin master

You will be asked to enter your GitHub username and password (or ssh key passphrase if you use GitHub with ssh).

Congratulations, you now have a copy of your current Open Peer Power Configuration on GitHub!

Step 6: Keeping your repository up to date

You should update your repository on a regular basis. Ideally after you make a major configuration change (new device, new component, etc.). The below script will update your repository with any changed configuration files and allow you to add a comment with the commit for tracking purposes:

gitupdate.sh

#!/bin/bash

cd /home/openpeerpower/.openpeerpower
source /srv/openpeerpower/bin/activate
opp --script check_config

git add .
git status
echo -n "Enter the Description for the Change: " [Minor Update]
read CHANGE_MSG
git commit -m "${CHANGE_MSG}"
git push origin master

exit

Every time you run this script, you will be prompted for a comment to describe the change(s) that you are committing. This comment will be displayed beside each changed file on GitHub and will be stored after each commit. You will also be asked to enter your GitHub username and password (or SSH key passphrase if you use GitHub with SSH).

Step 7: Configuration file testing

Travis CI is a continuous integration testing system that runs every time the code in your repository is updated and allows you to validate that your code works on a fresh install.

• Authorize Travis CI to have access to your GitHub repositories.
• Create the build script that Travis will run to test your repository.
• Create a dummy secrets.yaml for Travis.

Example .travis.yml

language: python
python:
  - "3.7"
before_install:
  - mv travis_secrets.yaml secrets.yaml
  - sudo apt-get install -y libudev-dev
install:
  - pip3 install openpeerpower
script:
  - opp -c . --script check_config

Since the secrets.yaml should not be stored in your repository for security reasons, you won’t be able to access it at build time. Creating a dummy secrets.yaml is as simple as creating a new file that mimics your existing secrets.yaml with the required keys, but not their value.

#travis_secrets.yaml
http_api: 000000000000000000000000
home_latitude: 00.00000
home_longitude: 00.0000
home_elevation: 0

Extra commands

You can enter these commands to get a list of the files in your local Git repository and a status of files that have changed but not committed yet:

git ls-files
git status

Examples:

openpeerpower@raspberrypi:~/.openpeerpower $ git ls-files
.gitignore
README.md
automation.yaml
configuration.yaml
customize.yaml
device_tracker.yaml
group.yaml
script.yaml

openpeerpower@raspberrypi:~/.openpeerpower $ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   .gitignore
        modified:   automation.yaml
        modified:   customize.yaml
        modified:   group.yaml

no changes added to commit (use "git add" and/or "git commit -a")