Merge pull request #144 from home-assistant/dev

Merge dev into master for 0.8.0 release

.github/CONTRIBUTING.md

@@ -0,0 +1,189 @@
+# Contributing to Hassbian-scripts
+
+Everybody is invited and welcome to contribute to Hassbian-scripts.
+
+The process is straight-forward.
+ - Read [How to get faster PR reviews](https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews) by Kubernetes (but skip step 0)
+ - Fork the Hassbian-scripts [git repository](https://github.com/home-assistant/hassbian-scripts).
+ - Add a new branch to your fork with a name that describe what you are implementing.
+ - Add or change the code.
+ - Ensure tests work.
+ - Ensure tests work. _Finding out during review that this does not work, will **not** result in a good review._
+ - Create a Pull Request against the [**dev**](https://github.com/home-assistant/hassbian-scripts/tree/dev) branch of Hassbian-scripts.
+
+## Pull Requests for new scripts.
+All new script must have meet the following criteria to even be reviewed:
+- Stickler-Ci should report no errors. (this is an automated review process based on [shellcheck](https://github.com/koalaman/shellcheck)
+- The Script must be tested with success locally, see [testing your code](#testing-your-code) for tips on how to test.
+- Every script should have an validation at the end, se [validation](#validation) for tips.
+- You **must** add [documentation](#documentation) to the /docs for the script.
+
+### PR Naming
+Create a good name for your PR, this will be used in the changelog.
+**Good names**  
+- Suite: Added support for feature X.
+- Hassbian-config: Added function X.
+- New install script for suite.
+- Suite: Fixed typo in function X.
+- Suite docs: Added more information about suite.
+
+**Bad names**  
+- Updated suite.sh
+- Fixed typo.
+
+### Description in the PR
+Remember that it is people that are reviewing your PR, pepole that most likly don't share your mindset.
+A good description of what the PR does, will certanly help during the review prosess.
+
+### Comments
+Your PR will most likly get comments during the review prosess, this is _not_ to criticise your work.
+But feeback on how your PR can better match our "standards", you should have a look at exsiting scripts in the [repo](https://github.com/home-assistant/hassbian-scripts/tree/dev/package/opt/hassbian/suites).
+If some comments are unclear to you, use the thread under that comment to get clarification, or drop a line in the #devs_hassbian channel over at [Discord](https://discord.gg/c5DvZ4e), we want to help you help us getting Hassbian-scripts better.
+
+## Structure of the hassbian-scripts
+The scripts in Hassbian-scripts are referred to as suites, these suites are bash scripts with an `.sh` file extension.
+Each suite is built up of functions, and every script should have at least these functions:
+ - suite-show-short-info.
+  - This info will be printed at the start when the script runs and is also used by `hassbian-config show`.
+	- This will typically include a short description of the suit.
+ - suite-show-long-info.
+  - This info will be printed when running `hassbian-config show suite`.
+	- This will typically include a longer description of the suit, and it's features.
+ - suite-show-copyright-info.
+  - This info will be printed at the start when the script runs and is also used by `hassbian-config show suite`.
+	- This will typically include the name/username and a link to github of the person writing the script.
+ - suite-install-package and or suite-upgrade-package, this is where the magic happens, this is where you include your script.
+
+## Spesial notations about install/upgrade functions
+### User inputs
+If your script require user inputs, they should be at the top of the function.
+And if possible have an option to use `--accept (-Y)` flag, to set default values and omit the input.
+Example:
+```bash
+function suite-install-package {
+  if [ "$ACCEPT" == "true" ]; then #This will be true if the suite is run with `--accept`
+    SUITE_USERNAME="pi"
+  else
+    echo
+    echo "Please take a moment to setup the suite."
+    echo -n "Enter a username of your choosing: "
+    read -r SUITE_USERNAME
+    if [ ! "$SUITE_USERNAME" ]; then
+        SUITE_USERNAME="pi" #Sets default if blank input is given.
+    fi
+    echo
+  fi
+```
+
+### Validation.
+There are multiple ways of validating if the script was successful, these are some examples:
+
+**Service**  
+This will check if there is a service with the name `shellinaboxd` running.
+```bash
+validation=$(pgrep -f shellinaboxd)
+if [ ! -z "${validation}" ]; then
+  echo
+  echo -e "\\e[32mInstallation done..\\e[0m"
+  echo
+  echo "You can now access the web terminal here: http://$ip_address:4200"
+  echo "You can also add this to your Home-Assistant config in an 'panel_iframe'"
+  echo
+else
+  echo
+  echo -e "\\e[31mInstallation failed..."
+  echo
+  return 1
+fi
+return 0
+```
+
+**pip package**  
+This will check if the pip package `cython` is installed in the virtual environment.
+```bash
+echo "Checking the installation..."
+validation=$(sudo -u homeassistant -H /bin/bash << EOF | grep Version | awk '{print $2}'
+source /srv/homeassistant/bin/activate
+pip3 show cython
+EOF
+)
+if [ ! -z "${validation}" ]; then
+  echo
+  echo -e "\\e[32mInstallation done..\\e[0m"
+  echo
+  echo "To continue have a look at https://home-assistant.io/components/tradfri/"
+  echo "It's recommended that you restart your Tradfri Gateway before continuing."
+  echo
+else
+  echo
+  echo -e "\\e[31mInstallation failed..."
+  echo
+  return 1
+fi
+return 0
+```
+
+**Command line tool**  
+This will check if `psql` is a valid command.
+```bash
+validation=$(which psql)
+if [ ! -z "${validation}" ]; then
+  echo
+  echo -e "\\e[32mInstallation done..\\e[0m"
+  echo
+  echo "No database or database user is created during this setup and will need to be created manually."
+  echo
+  echo "To continue have a look at https://home-assistant.io/components/recorder/"
+  echo
+else
+  echo
+  echo -e "\\e[31mInstallation failed..."
+  echo
+  return 1
+fi
+return 0
+```
+
+**Config change**  
+This example will check the value, if blank it will print "Installation Failed"  
+```bash
+validation=$(getcap /usr/bin/python3.5 | awk -F'= ' '{print $NF}')
+if [ ! -z "${validation}" ]; then
+  echo
+  echo -e "\\e[32mInstallation done..\\e[0m"
+  echo
+  echo "To continue have a look at https://home-assistant.io/components/emulated_hue/"
+  echo
+else
+  echo
+  echo -e "\\e[31mInstallation failed..."
+  echo
+  return 1
+fi
+return 0
+```
+
+## Testing your code
+Testing the code can be done in the folowing steps:
+1. Make sure you have the newest version from the upstream dev. branch. `sudo hassbian-config upgrade hassbian-script-dev`
+2. Put your `suite.sh` file in the `/opt/hassbian/suites/` directory.
+3. Run test with `sudo hassbian-config install suite` and/or `sudo hassbian-config upgrade suite`
+	- If you added support for `-y` test this to.
+
+## Documentation
+First create a new `suite.md` file in the /docs directory in your fork.
+There can never be too much documentation, the file should have a minimum of:
+- Description
+- Installation and/or upgrade line/lines
+- Who made the script.
+
+It should also contains if possible:
+- Log location
+- Configuration location.
+- Service commands (start, stop, restart, status)
+- Defaults:
+	- username
+	- password
+	- port
+
+When the `suite.md` is finished, add it as an link in the README.md

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,19 @@
+Make sure your running an up to date version of Hassbian before reporting a problem. If not make sure to specify what version and why so we can recreate the issue in question.
+
+You should only file an issue if you found a bug. Feature and enhancement requests should go in [#33](https://github.com/home-assistant/hassbian-scripts/issues/33) that's dedicated for this usage.
+
+**Hassbian-config version (`hassbian-config -V`):**  
+
+**Script/Suite:**
+
+**Description of problem:**  
+
+**Expected:**
+
+
+**Traceback/log (if applicable):**
+```bash
+
+```
+
+**Additional info:**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+### Description:
+
+**Related issue (if applicable):** Fixes #<hassbian-scripts issue number goes here>
+
+### Checklist:
+  - [ ] The code change is tested and works locally.
+  - [ ] Script has validation check of the job.
+
+#### If pertinent:
+  - [ ] Created/Updated documentation at `/docs`
+

.stickler.yml

@@ -0,0 +1,4 @@
+linters:
+  shellcheck:
+    shell: bash
+    exclude: 'SC1090'

README.md

@@ -1,6 +1,6 @@
 ## Hassbian-scripts
-These are the scripts used in the [HASSbian](https://github.com/home-assistant/pi-gen) image.
-The scripts in this repository where made to be used with the HASSbian image and the included Home Assistant instance.  
+These are the scripts used in the [Hassbian](https://github.com/home-assistant/pi-gen) image.
+The scripts in this repository where made to be used with the Hassbian image and the included Home Assistant instance.  
 
 
 ## The included scripts
@@ -9,7 +9,7 @@ The following scripts are currently included. You can view the documentation bel
 * [hassbian-config](/docs/hassbian_config.md)
   * [AppDaemon](/docs/appdaemon.md)
   * [Duck DNS](/docs/duckdns.md)
-  * [HASSbian](/docs/hassbian.md)
+  * [Hassbian](/docs/hassbian.md)
   * [Home Assistant](/docs/homeassistant.md)
   * [Homebridge](/docs/homebridge.md)
   * [HUE](/docs/hue.md)
@@ -26,7 +26,7 @@ The following scripts are currently included. You can view the documentation bel
 
 ***
 ## Raspbian Jessie
-If this package is used with a Debian Jessie based distrbution then you need to uncomment the source repositores in  `/etc/apt/sources.list`
+If this package is used with a Debian Jessie based distribution then you need to uncomment the source repositories in  `/etc/apt/sources.list`
 
 ```text
 # Uncomment line below then 'apt-get update' to enable 'apt-get source'

docs/appdaemon.md

@@ -3,12 +3,12 @@ This Installs AppDaemon in a separate Venv onto this system.
 For more information about AppDaemon see the [documentation.](http://appdaemon.readthedocs.io/en/latest/)
 
 ## Installation
-```
+```bash
 $ sudo hassbian-config install appdaemon
 ```
 
 ## Upgrade
-```
+```bash
 $ sudo hassbian-config upgrade appdaemon
 ```
 
@@ -20,12 +20,17 @@ Stop service: `sudo systemctl stop appdaemon@homeassistant.service`
 Restart service: `sudo systemctl restart appdaemon@homeassistant.service`  
 Service status: `sudo systemctl status appdaemon@homeassistant.service`  
 Enter the virtual environment where AppDaemon is installed as `homeassistant`:
-```
-sudo su -s /bin/bash homeassistant
-source /srv/homeassistant/bin/activate
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ source /srv/appdaemon/bin/activate
 ```
 When you are done, type `exit` to return to the `pi` user.
 
+To manually start AppDaemon, enter the AppDaemon virtual environment as described above, and then type this to start it:
+```bash
+$ appdaemon -c /home/homeassistant/appdaemon/
+```
+
 ***
 The installation script was originally contributed by [@Landrash](https://github.com/landrash).  
 The upgrade script was originally contributed by [@Ludeeus](https://github.com/ludeeus).

docs/duckdns.md

@@ -10,7 +10,7 @@ $ sudo hassbian-config install duckdns
 ## Additional info
 Running as: `homeassistant`  
 
-If you choose to aslo generate SSL certificates with this you would need to add this under `http:` to your `configuration.yaml`
+If you choose to also generate SSL certificates with this you would need to add this under `http:` to your `configuration.yaml`
 ```
   ssl_certificate: /home/homeassistant/dehydrated/certs/YOURDOMAIN.duckdns.org/fullchain.pem
   ssl_key: /home/homeassistant/dehydrated/certs/YOURDOMAIN.duckdns.org/privkey.pem

docs/hassbian_config.md

@@ -12,14 +12,18 @@ where command is one of:
 - `show` This will show you all available suites.
 - `log` This will show you the log of last hassbian-config operation.
 - `share-log` This will generate an hastebin link of the last hassbian-config operation.
-- `-V` This will show you the installed version of `hassbian-config`.
 
 Optional flags:
-- `-y` This will accept defaults on scripts that allow this.
-- `-f` This will force run an script. This is useful if you need to reinstall a package.
+- `-Y | --accept` This will accept defaults on scripts that allow this.
+- `-F | --force` This will force run an script. This is useful if you need to reinstall a package.
+- `-D | --debug` This will output every comand to the console.
+
+Other available commands:
+- `-V | --version` This will show you the installed version of `hassbian-config`.
+- `-H | --help` Shows help for the tool, with all available commands.
 
 ## Installation
-This package is pre-installed on the [HASSbian image](https://github.com/home-assistant/pi-gen/releases).
+This package is pre-installed on the [Hassbian image](https://github.com/home-assistant/pi-gen/releases).
 This package can be used with Raspbian lite but it's not recommended.
 ```
 $ curl https://api.github.com/repos/home-assistant/hassbian-scripts/releases/latest | grep "browser_download_url.*deb" | cut -d : -f 2,3 | tr -d \" | wget -qi -

docs/homeassistant.md

@@ -10,7 +10,7 @@ $ sudo hassbian-config install homeassistant
 
 ## Upgrade
 ```
-$ sudo hassbian-config upgrade home-assistant
+$ sudo hassbian-config upgrade homeassistant
 ```
 
 ## Additional info

docs/homebridge.md

@@ -1,18 +1,18 @@
 ## Description
 This script will install and configure Homebridge to be used with Home Assistant.
-This will allow you to controll your home with Apple's HomeKit (Siri on iOS, OSX and AppleTV).
+This will allow you to control your home with Apple's HomeKit (Siri on iOS, OSX and AppleTV).
 By default all devices are hidden, and you will need to add som entries in your `customize.yaml` configuration.
 You can learn more about this in the [Home Assistant for Homebridge repo.](https://github.com/home-assistant/homebridge-homeassistant#customization)  
 
-_NB!: This install script will fail resulting in your Pi to reboot, if you do not use an recomended level powersupply._
+_NB!: This install script will fail resulting in your Pi to reboot, if you do not use an recommended level power supply._
 
 ## Installation
 ```
 $ sudo hassbian-config install homebridge
 ```
 
 ## Upgrade
-No script avaiable, maybe you could write one?  
+No script available, maybe you could write one?  
 If so, add an PR here when you are done:  
 [homeassistant/hassbian-scripts](https://github.com/home-assistant/hassbian-scripts/pulls)
 

docs/libcec.md

@@ -1,5 +1,5 @@
 ## Description
-**This scipt is currently brooken upstream since it currently doesn't build properly for Python >3.4**
+**This script is currently broken upstream since it currently doesn't build properly for Python >3.4**
 This script installs libcec and it dependencies. Further more this script symlinks the system wide packages to the Home Assistant venv so they can be used with Home Assistant.
 
 ## Installation
@@ -8,7 +8,7 @@ $ sudo hassbian-config install libcec
 ```
 
 ## Upgrade
-No script avaiable, maybe you could write one?  
+No script available, maybe you could write one?  
 If so, add an PR here when you are done:  
 [homeassistant/hassbian-scripts](https://github.com/home-assistant/hassbian-scripts/pulls)
 

docs/mariadb.md

@@ -7,7 +7,7 @@ $ sudo hassbian-config install mariadb
 ```
 
 ## Upgrade
-No script avaiable, maybe you could write one?  
+No script available, maybe you could write one?  
 If so, add an PR here when you are done:  
 [homeassistant/hassbian-scripts](https://github.com/home-assistant/hassbian-scripts/pulls)
 

docs/mosquitto.md

@@ -7,7 +7,7 @@ $ sudo hassbian-config install mosquitto
 ```
 
 ## Upgrade
-No script avaiable, maybe you could write one?  
+No script available, maybe you could write one?  
 If so, add an PR here when you are done:  
 [homeassistant/hassbian-scripts](https://github.com/home-assistant/hassbian-scripts/pulls)