Re-organisation Documentation and Getting started (#2055)

* Split MQTT documentation * Add more details * Move content to /docs * Enable sidebar * Move content to /docs * Enable sidebar * Move content * Update links * Remove wizard stuff * Enable sidebar * Minor changes * Move MQTT parts to /docs * update links * Update links and sync content * Fix link * Enable sidebar * Remove navigation * Remove navigation and other minor updates * Update links * Add overview page * Make title linkable * Update * Plit content * Update links * Rearrange content * New getting-started section * Add icons for docs * Update for new structure * Update for new structure * Add docs navigation * Add docs overview page * Remove ecosystem navigation * Add docs and remove other collections * Move ecosystem to docs * Remove duplicate files * Re-add ecosystem overview * Move to ecosystem * Fix permission * Update navigation * Remove collection * Move overview to right folder * Move mqtt to upper level * Move notebook to ecosystem * Remove un-used files * Add one more rectangle for iOS * Move two parts back from docs and rename Run step * Remove colon * update getting-started section * Add redirect * Update * Update navigation
2017-02-23 11:09:41 +01:00 · 2017-02-23 11:09:41 +01:00 · 481320128f
commit 481320128f
parent 0677895b5b
138 changed files with 1309 additions and 909 deletions
--- a/source/_docs/installation/docker.markdown
+++ b/source/_docs/installation/docker.markdown
@ -0,0 +1,38 @@
+---
+layout: page
+title: "Installation on Docker"
+description: "Instructions to install Home Assistant on a Docker."
+date: 2016-04-16 11:36
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-docker/
+---
+
+Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/` points at the folder where you want to store your config and run it:
+
+### {% linkable_title Linux %}
+
+```bash
+$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
+```
+
+### {% linkable_title macOS %}
+
+When using `boot2docker` on macOS you are unable to map the local time to your Docker container. Use `-e "TZ=America/Los_Angeles"` instead of `-v /etc/localtime:/etc/localtime:ro`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+Additionally, if your expectation is that you will be able to browse directly to `http://localhost:8123` on your macOS host, then you will also need to replace the `--net=host` switch with `-p 8123:8123`. This is currently the only way to forward ports on to your actual host (macOS) machine instead of the virtual machine inside `xhyve`. More detail on this can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10).
+
+```bash
+$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant
+```
+
+### {% linkable_title Restart %}
+
+This will launch Home Assistant and serve the web interface from port 8123 on your Docker host.
+
+If you change the configuration you have to restart the server. To do that you have 2 options.
+
+ 1. You can go to the <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> service developer tools, select the service `homeassistant/restart` and click "Call Service".
+ 2. Or you can restart it from an terminal by running `docker restart home-assistant`
--- a/source/_docs/installation/python.markdown
+++ b/source/_docs/installation/python.markdown
@ -0,0 +1,32 @@
+---
+layout: page
+title: "Installation on your computer"
+description: "Installation of Home Assistant on your computer."
+date: 2014-12-18 22:57
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-python/
+---
+
+Once Python is installed, execute the following code in a console:
+
+```bash
+$ pip3 install homeassistant
+$ hass --open-ui
+```
+
+Running these commands will:
+
+ - Install Home Assistant
+ - Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123)
+
+If you're running a Linux-based platform, we suggest you follow the [VirtualEnv instructions](/docs/installation/virtualenv/) to avoid using `root`.
+
+Video tutorials of this process for various operating systems are available here:
+
+ - [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY)
+ - [macOS](https://www.youtube.com/watch?v=hej6ipN86ls)
+ - [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0)
+
--- a/source/_docs/installation/raspberry-pi-all-in-one.markdown
+++ b/source/_docs/installation/raspberry-pi-all-in-one.markdown
@ -0,0 +1,115 @@
+---
+layout: page
+title: "Raspberry Pi All-In-One Installer"
+date: 2016-05-12 01:39
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-raspberry-pi-all-in-one/
+---
+
+The [Raspberry Pi All-In-One Installer](https://github.com/home-assistant/fabric-home-assistant) deploys a complete Home Assistant server including support for MQTT with websockets, Z-Wave, and the Open-Zwave Control Panel.
+
+The only requirement is that you have a Raspberry Pi with a fresh installation of [Raspbian](https://www.raspberrypi.org/downloads/raspbian/) connected to your network.
+
+<p class='note'>
+Note that as of 2016-11-30 SSH is disabled by default in the official Raspbian images.  Adding an empty file called `ssh` to `/boot/` or the FAT32 partition will enable it.  More information is on the Raspberry Pi Foundation [Blog](https://www.raspberrypi.org/blog/page/2/?fish#a-security-update-for-raspbian-pixel)
+</p>
+
+*  Login to Raspberry Pi. For example with `ssh pi@your_raspberry_pi_ip`
+*  Run the following command
+
+```bash
+$ curl -O https://raw.githubusercontent.com/home-assistant/fabric-home-assistant/master/hass_rpi_installer.sh && sudo chown pi:pi hass_rpi_installer.sh && bash hass_rpi_installer.sh
+```
+<p class='note warning'>
+  Note this command is one-line and not run as sudo.
+</p>
+
+Installation will take approx. 1-2 hours depending on the Raspberry Pi model the installer is being run against. The installer will identitfy what Raspberry PI hardware revision you are using and adjust commands accordingly. A complete log of the install is located at: `/home/pi/fabric-home-assistant/installation_report.txt` The installer has been updated to simply log any errors encountered, but resume installing. Please consult the "installation report" if your install encountered issues. 
+
+[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=VGl3KTrYo6s) explaining how to install Raspbian on your Raspberry Pi and install Home Assistant using the All-In-One Installer.
+
+Once rebooted, your Raspberry Pi will be up and running with Home Assistant. You can access it at [http://your_raspberry_pi_ip:8123](http://your_raspberry_pi_ip:8123).
+
+The Home Assistant configuration is located at `/home/homeassistant/.homeassistant` (or `/home/hass/.homeassistant` if installed prior to December 2016). The [virtualenv](https://virtualenv.pypa.io/en/latest/) with the Home Assistant installation is located at `/srv/homeassistant/homeassistant_venv`. As part of the secure installation, a new user (**homeassistant**) is added to your Raspberry Pi to run Home Assistant. This is a system account and does not have login or other abilities by design. When editing your `configuration.yaml` files, you will need to run the commands with `sudo` or by switching user.
+
+<p class='note note'>
+  *Windows users*: Setting up WinSCP to allow this seemlessly is at the end of this page.
+</p>
+
+By default, installation makes use of a Python Virtualenv. If you wish to not follow this recommendation, you may add the flag `-n` to the end of the install command specified above.
+
+The All-In-One Installer script will do the following automatically:
+
+*  Create all needed directories
+*  Create needed service accounts
+*  Install OS and Python dependencies
+*  Setup a python virtualenv to run Home Assistant and components inside.
+*  Run as `homeassistant` service account
+*  Install Home Assistant in a virtualenv
+*  Install Mosquitto with websocket support running on ports 1883 and 9001
+*  Build and Install Python-openzwave in the Home Assistant virtualenv
+*  Build openzwave-control-panel in `/srv/homeassistant/src/open-zwave-control-panel`
+*  Add Home Assistant to systemd services to start at boot
+
+### {% linkable_title Upgrading %}
+
+To upgrade the All-In-One setup manually:
+
+*  Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
+*  Change to homeassistant user `sudo su -s /bin/bash homeassistant`
+*  Change to virtual enviroment `source /srv/homeassistant/homeassistant_venv/bin/activate`
+*  Update HA `pip3 install --upgrade homeassistant`
+*  Type `exit` to logout the hass user and return to the `pi` user.
+
+<p class='note note'>
+If you deployed Home Assistant via the AiO installer prior to December 2016, replace `sudo su -s /bin/bash homeassistant` with `sudo su -s /bin/bash hass` and `source /srv/homeassistant/homeassistant_venv/bin/activate` with `source /srv/hass/hass_venv/bin/activate`</p>
+
+  
+To upgrade with fabric:
+
+*  Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
+*  Change to `cd ~/fabric-home-assistant`
+*  Run `fab upgrade_homeassistant`
+  
+After upgrading, you can restart Home Assistant a few different ways:
+
+* Restarting the Raspberry Pi `sudo reboot`
+* Restarting the Home-Assistant Service `sudo systemctl restart home-assistant.service`
+
+### {% linkable_title To change the MQTT default password %} 
+ 
+*  Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
+*  Change password `sudo mosquitto_passwd /etc/mosquitto/pwfile pi`
+*  Restart mosquitto `sudo systemctl restart mosquitto.service`
+*  Be sure to update your `configuration.yaml` to reflect the new password.
+
+### {% linkable_title Using the OZWCP web application %}
+
+To launch the OZWCP web application:
+
+*  Make sure Home Assistant is not running! So stop that first
+*  Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
+*  Change to the ozwcp directory `cd /srv/homeassistant/src/open-zwave-control-panel/`
+*  Launch the control panel `sudo ./ozwcp -p 8888`
+*  Open a web browser to `http://your_pi_ip:8888`
+*  Specify your zwave controller, for example `/dev/ttyACM0` and hit initialize
+
+<p class='note note'>
+If you deployed Home Assistant via the AiO installer prior to December 2016, replace `cd /srv/homeassistant/src/open-zwave-control-panel/` with `cd /srv/hass/src/open-zwave-control-panel/`
+</p>
+
+<p class='note warning'>
+Don't check the USB box regardless of using a USB based device.
+</p>
+
+### {% linkable_title Using the GPIOs %}
+
+The (**homeassistant**) user is added to the GPIO group as part of the install now.
+
+### {% linkable_title WinSCP %}
+
+If you are Windows users who is using [WinSCP](https://winscp.net/), please note that after running the installer, you will need to modify settings allowing you to "switch users" to edit your configuration files. 
+
+First create a new session on WinSCP using Protocol **SCP** pointing to your Pi IP address and port 22 and then modify the needed setting by click on **Advanced...** -> **Environment** -> **SCP/Shell** -> **Shell** and selecting `sudo su -`.
--- a/source/_docs/installation/raspberry-pi.markdown
+++ b/source/_docs/installation/raspberry-pi.markdown
@ -0,0 +1,77 @@
+---
+layout: page
+title: "Manual installation on a Raspberry Pi"
+description: "Instructions to install Home Assistant on a Raspberry Pi runnning Raspbian Lite."
+date: 2016-09-05 16:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-raspberry-pi/
+---
+
+This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/). The installation will be installed in a [Virtual Environment](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite.
+
+Connect to the Raspberry Pi over SSH. Default password is `raspberry`.
+You will need to enable SSH access. The Raspberry Pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/).
+
+```bash
+$ ssh pi@ipadress
+```
+
+Changing the default password is encouraged.
+
+```bash
+$ passwd
+```
+
+Update the system.
+
+```bash
+$ sudo apt-get update
+$ sudo apt-get upgrade -y
+```
+
+Install the dependencies.
+
+```bash
+$ sudo apt-get install python3 python3-venv python3-pip
+```
+
+Add an account for Home Assistant called `homeassistant`.
+Since this account is only for running Home Assistant the extra arguments of `-rm` is added to create a system account and create a home directory.
+
+```bash
+$ sudo useradd -rm homeassistant
+```
+
+Next we will create a directory for the installation of Home Assistant and change the owner to the `homeassistant` account.
+
+```bash
+$ cd /srv
+$ sudo mkdir homeassistant
+$ sudo chown homeassistant:homeassistant homeassistant
+```
+
+Next up is to create and change to a virtual environment for Home Assistant. This will be done as the `homeassistant` account.
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ cd /srv/homeassistant
+$ python3 -m venv .
+$ source bin/activate
+```
+Once you have activated the virtual environment you will notice the prompt change and then you can install Home Assistant.
+
+```bash
+(homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ pip3 install homeassistant
+```
+
+Start Home Assistant for the first time. This will complete the installation, create the `.homeasssistant` configuration directory in the `/home/homeassistant` directory and install any basic dependencies.
+
+```bash
+(homeassistant) $ hass
+```
+
+You can now reach your installation on your Raspberry Pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123).
+
--- a/source/_docs/installation/synology.markdown
+++ b/source/_docs/installation/synology.markdown
@ -0,0 +1,228 @@
+---
+layout: page
+title: "Installation on a Synology NAS"
+description: "Instructions to install Home Assistant on a Synology NAS."
+date: 2016-04-16 11:36
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-synology/
+---
+
+The following configuration has been tested on Synology 413j running DSM 6.0-7321 Update 1.
+
+Running these commands will:
+
+ - Install Home Assistant
+ - Enable Home Assistant to be launched on [http://localhost:8123](http://localhost:8123)
+
+Using the Synology webadmin:
+
+ - Install python3 using the Synology Package Center
+ - Create homeassistant user and add to the "users" group
+
+SSH onto your synology & login as admin or root
+
+ - Log in with your own administrator account
+ - Switch to root using:
+
+```bash
+$ sudo -i
+```
+
+
+Check the path to python3 (assumed to be /volume1/@appstore/py3k/usr/local/bin)
+
+```bash
+$ cd /volume1/@appstore/py3k/usr/local/bin
+```
+
+Install PIP (Python's package management system)
+
+```bash
+$ ./python3 -m ensurepip
+```
+
+Use PIP to install Homeassistant package
+
+```bash
+$ ./python3 -m pip install homeassistant
+```
+
+Create homeassistant config directory & switch to it
+
+```bash
+$ mkdir /volume1/homeassistant
+$ cd /volume1/homeassistant
+```
+
+Create hass-daemon file using the following code (edit the variables in uppercase if necessary)
+
+```bash
+#!/bin/sh
+
+# Package
+PACKAGE="homeassistant"
+DNAME="Home Assistant"
+
+# Others
+USER="homeassistant"
+PYTHON_DIR="/volume1/@appstore/py3k/usr/local/bin"
+PYTHON="$PYTHON_DIR/python3"
+HASS="$PYTHON_DIR/hass"
+INSTALL_DIR="/volume1/homeassistant"
+PID_FILE="$INSTALL_DIR/home-assistant.pid"
+FLAGS="-v --config $INSTALL_DIR --pid-file $PID_FILE --daemon"
+REDIRECT="> $INSTALL_DIR/home-assistant.log 2>&1"
+
+start_daemon ()
+{
+    sudo -u ${USER} /bin/sh -c "$PYTHON $HASS $FLAGS $REDIRECT;"
+}
+
+stop_daemon ()
+{
+    kill `cat ${PID_FILE}`
+    wait_for_status 1 20 || kill -9 `cat ${PID_FILE}`
+    rm -f ${PID_FILE}
+}
+
+daemon_status ()
+{
+    if [ -f ${PID_FILE} ] && kill -0 `cat ${PID_FILE}` > /dev/null 2>&1; then
+        return
+    fi
+    rm -f ${PID_FILE}
+    return 1
+}
+
+wait_for_status ()
+{
+    counter=$2
+    while [ ${counter} -gt 0 ]; do
+        daemon_status
+        [ $? -eq $1 ] && return
+        let counter=counter-1
+        sleep 1
+    done
+    return 1
+}
+
+case $1 in
+    start)
+        if daemon_status; then
+            echo ${DNAME} is already running
+            exit 0
+        else
+            echo Starting ${DNAME} ...
+            start_daemon
+            exit $?
+        fi
+        ;;
+    stop)
+        if daemon_status; then
+            echo Stopping ${DNAME} ...
+            stop_daemon
+            exit $?
+        else
+            echo ${DNAME} is not running
+            exit 0
+        fi
+        ;;
+        restart)
+        if daemon_status; then
+            echo Stopping ${DNAME} ...
+            stop_daemon
+            echo Starting ${DNAME} ...
+            start_daemon
+            exit $?
+        else
+            echo ${DNAME} is not running
+            echo Starting ${DNAME} ...
+            start_daemon
+            exit $?
+        fi
+        ;;
+    status)
+        if daemon_status; then
+            echo ${DNAME} is running
+            exit 0
+        else
+            echo ${DNAME} is not running
+            exit 1
+        fi
+        ;;
+    log)
+        echo ${LOG_FILE}
+        exit 0
+        ;;
+    *)
+        exit 1
+        ;;
+esac
+
+```
+
+Create links to python folders to make things easier in the future:
+
+```bash
+$ ln -s /volume1/@appstore/py3k/usr/local/bin python3
+$ ln -s /volume1/@appstore/py3k/usr/local/lib/python3.5/site-packages/homeassistant
+```
+
+Set the owner and permissions on your config folder
+
+```bash
+$ chown -R homeassistant:users /volume1/homeassistant
+$ chmod -R 664 /volume1/homeassistant
+```
+
+Make the daemon file executable:
+
+```bash
+$ chmod 777 /volume1/homeassistant/hass-daemon
+```
+
+Update your firewall (if it is turned on on the Synology device):
+
+ - Go to your Synology control panel
+ - Go to security 
+ - Go to firewall
+ - Go to Edit Rules
+ - Click Create
+ - Select Custom: Destination port "TCP"
+ - Type "8123" in port
+ - Click on OK
+ - Click on OK again
+
+
+Copy your configuration.yaml file into the config folder
+That's it... you're all set to go
+
+Here are some useful commands:
+
+- Start Home Assistant:
+
+```bash
+$ sudo /volume1/homeassistant/hass-daemon start
+```
+
+- Stop Home Assistant:
+
+```bash
+$ sudo /volume1/homeassistant/hass-daemon stop
+```
+
+- Restart Home Assistant:
+
+```bash
+$ sudo /volume1/homeassistant/hass-daemon restart
+```
+
+- Upgrade Home Assistant::
+
+```bash
+$  /volume1/@appstore/py3k/usr/local/bin/python3 -m pip install --upgrade homeassistant
+```
+
--- a/source/_docs/installation/troubleshooting.markdown
+++ b/source/_docs/installation/troubleshooting.markdown
@ -0,0 +1,77 @@
+---
+layout: page
+title: "Troubleshooting installation problems"
+description: "Common installation problems and their solutions."
+date: 2015-01-20 22:36
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/troubleshooting/
+---
+
+It can happen that you run into trouble while installing Home Assistant. This page is here to help you solve the most common problems.
+
+
+#### {% linkable_title pip3: command not found %}
+This utility should have been installed as part of the Python 3.4 installation. Check if Python 3.4 is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/).
+
+If you are able to successfully run `python3 --version` but not `pip3`, install Home Assistant by running the following command instead:
+
+```bash
+$ python3 -m pip install homeassistant
+```
+
+On a Debian system, you can also install python3 by `sudo apt-get install python3`, and pip3 by `sudo apt-get install python3-pip`.
+
+#### {% linkable_title No module named pip %}
+[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is omitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and running it with Python 3:
+
+```bash
+$ python3 get-pip.py
+```
+
+#### {% linkable_title libyaml is not found or a compiler error %}
+
+On a Debian system, install the Python 3 YAML library by `sudo apt-get install python3-yaml`.
+
+#### {% linkable_title distutils.errors.DistutilsOptionError: must supply either home or prefix/exec-prefix -- not both %}
+This is a known issue if you're on a Mac using Homebrew to install Python. Please follow [these instructions](https://github.com/Homebrew/brew/blob/master/docs/Homebrew-and-Python.md#note-on-pip-install---user) to resolve it.
+
+#### {% linkable_title CentOS and Python 3 %}
+To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL, [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python34/) needs to be activated.
+
+#### {% linkable_title No access to the frontend %}
+In newer Linux distributions (at least Fedora > 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and macOS machines may also have issues with this.
+
+To fix this you will need to open your machine's firewall for TCP traffic to port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here.
+
+- [Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7)
+- [macOS instructions](https://support.apple.com/en-us/HT201642)
+
+For systems with **firewalld** (Fedora, CentOS/RHEL, etc.):
+
+```bash
+$ sudo firewall-cmd --permanent --add-port=8123/tcp
+$ sudo firewall-cmd --reload
+```
+
+For UFW systems (Ubuntu, Debian, Raspbian, etc.):
+
+```bash
+$ sudo ufw allow 8123/tcp
+```
+
+For `iptables` systems (was the default for older distributions):
+
+```bash
+$ iptables -I INPUT -p tcp --dport 8123 -j ACCEPT
+$ iptables-save > /etc/network/iptables.rules  # your rules may be saved elsewhere
+```
+
+#### {% linkable_title After upgrading, your browser login gets stuck at the "loading data" step %}
+After upgrading to a new version, you may notice your browser gets stuck at the "loading data" login screen. Close the window/tab and go into your browser settings and delete all the cookies for your URL. You can then log back in and it should work. 
+
+Android Chrome 
+chrome -> settings -> site settings -> storage -> search for your URL for home assistant-> "clear & reset"
+
--- a/source/_docs/installation/updating.markdown
+++ b/source/_docs/installation/updating.markdown
@ -0,0 +1,49 @@
+---
+layout: page
+title: "Updating Home Assistant"
+description: "Step to update Home Assistant."
+date: 2016-05-04 10:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/hassbian-upgrading/
+---
+
+<p class='note warning'>
+The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [HASSbian](/docs/hassbian/common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/#upgrading), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant).
+</p>
+
+The default way to update Home Assistant to the latest release, when available, is:
+
+```bash
+$ pip3 install --upgrade homeassistant
+```
+
+After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/docs/autostart/) daemon (if applicable)
+
+<p class='note'>
+  To avoid permission errors, the upgrade must be run as the same user as the installation was completed, again review the documentation specific to your install [HASSbian](/docs/hassbian/installation/), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv).
+</p>
+
+[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant.
+
+#### {% linkable_title Run a specific version %}
+
+In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release:
+
+```bash
+$ pip3 install homeassistant==0.XX.X
+```
+
+#### {% linkable_title Run the development version %}
+
+If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to `dev`. 
+
+<p class='note warning'>
+  The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption.
+</p>
+
+```bash
+$ pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev
+```
--- a/source/_docs/installation/vagrant.markdown
+++ b/source/_docs/installation/vagrant.markdown
@ -0,0 +1,89 @@
+---
+layout: page
+title: "Installation on Vagrant"
+description: "Instructions to run Home Assistant on a Vagrant VM."
+date: 2016-05-28 10:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-vagrant/
+---
+
+A `Vagrantfile` is available into `virtualization/vagrant` folder for quickly spinning up a Linux virtual machine running Home Assistant. This can be beneficial for those who want to experiment with Home Assistant and/or developers willing to easily test local changes and run test suite against them.
+
+<p class='note'>
+Vagrant is intended for testing/development only. It is NOT recommended for permanent installations.
+</p>
+
+## {% linkable_title Install Vagrant %}
+
+You must have [Vagrant](https://www.vagrantup.com/downloads.html) and [Virtualbox](https://www.virtualbox.org/wiki/Downloads) installed on your workstation.
+
+## {% linkable_title Get Home Assistant source code %}
+
+Download the Home Assistant source code by either downloading the .zip file from [GitHub releases page](https://github.com/home-assistant/home-assistant/releases) or by using [Git](https://git-scm.com/)
+
+```bash
+$ git clone https://github.com/home-assistant/home-assistant.git
+$ cd home-assistant/virtualization/vagrant
+```
+
+<p class='note'>
+The following instructions will assume you changed your working directory to be `home-assistant/virtualization/vagrant`. This is mandatory because Vagrant will look for informations about the running VM inside that folder and won't work otherwise
+</p>
+
+<p class='note'>
+When using Vagrant on Windows, change git's `auto.crlf` to input before cloning the Home Assistant repository. With input setting git won't automatically change line endings from Unix LF to Windows CRLF. Shell scripts executed during provision won't work with Windows line endings.
+</p>
+
+```bash
+$ git config --global core.autocrlf input
+```
+
+## {% linkable_title Create the Vagrant VM and start Home Assistant %}
+
+```bash
+$ vagrant up
+```
+
+This will download and start a virtual machine using Virtualbox, which will internally setup the development environment necessary to start Home Assistant process and run test suite as well. After the VM has started successfully, the Home Assistant frontend will be accessible locally from your browser at [http://localhost:8123](http://localhost:8123)
+
+## {% linkable_title Stopping Vagrant %}
+
+To shutdown the Vagrant host:
+
+```bash
+$ vagrant halt
+```
+
+To start it again, just run `vagrant up`
+
+## {% linkable_title Restarting Home Assistant process to test changes %}
+
+The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Configuration section](/docs/configuration/) in the docmentation for more information about how to configure Home Assistant).
+
+Any changes made to the local directory on your workstation will be available from the Vagrant host, so to apply your changes to the Home Assistant process, just restart it:
+
+```bash
+$ touch restart ; vagrant provision
+```
+
+## {% linkable_title Run test suite (Tox) %}
+
+To run tests against your changes:
+
+```bash
+$ touch run_tests ; vagrant provision
+```
+
+## {% linkable_title Cleanup %}
+
+To completely remove the VM:
+
+```bash
+$ rm setup_done ; vagrant destroy -f
+```
+
+You can now recreate a completely new Vagrant host with `vagrant up`
+
--- a/source/_docs/installation/virtualenv.markdown
+++ b/source/_docs/installation/virtualenv.markdown
@ -0,0 +1,133 @@
+---
+layout: page
+title: "Installation in virtualenv"
+description: "Instructions how to install Home Assistant in a virtual environment."
+date: 2016-4-16 16:40
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-virtualenv/
+---
+
+There are several reasons why it makes sense to run Home Assistant in a virtual environment. A [virtualenv](https://virtualenv.pypa.io/en/latest/) encapsulates all aspect of a Python environment within a single directory tree. That means the Python packages you install for Home Assistant won't interact with the rest of your system and vice-versa. It means a random upgrade for some other program on your computer won't break Home Assistant, and it means you don't need to install Python packages as root.
+
+Virtualenvs are pretty easy to setup. This example will walk through one method of setting one up (there are certainly others). We'll be using Debian in this example (as many Home Assistant users are running Raspbian on a Raspberry Pi), but all of the Python related steps should be the same on just about any platform.
+
+### {% linkable_title Step 0: Install some dependencies %}
+
+```bash
+$ sudo apt-get update
+$ sudo apt-get upgrade
+$ sudo apt-get install python-pip python3-dev
+$ sudo pip install --upgrade virtualenv
+```
+
+### {% linkable_title Step 1: Create a Home Assistant user %}
+
+This step is optional, but it's a good idea to give services like Home Assistant their own user. It gives you more granular control over permissions, and reduces the exposure to the rest of your system in the event there is a security related bug in Home Assistant. This is a reasonably Linux oriented step, and will look different on other operating systems (or even other Linux distributions).
+
+```bash
+$ sudo adduser --system homeassistant
+```
+
+Home Assistant stores its configuration in `$HOME/.homeassistant` by default, so in this case, it would be in `/home/homeassistant/.homeassistant`
+
+If you plan to use a Z-Wave controller, you will need to add this user to the `dialout` group
+
+```bash
+$ sudo usermod -G dialout -a homeassistant
+```
+
+### {% linkable_title Step 2: Create a directory for Home Assistant %}
+
+This can be anywhere you want. As example we put it in `/srv`. You also need to change the ownership of the directory to the user you created above (if you created one).
+
+```bash
+$ sudo mkdir /srv/homeassistant
+$ sudo chown homeassistant:homeassistant /srv/homeassistant
+```
+
+### {% linkable_title Step 3: Become the new user %}
+
+This is obviously only necessary if you created a `homeassistant` user, but if you did, be sure to switch to that user whenever you install things in your virtualenv, otherwise you'll end up with mucked up permissions.
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+```
+
+The `su` command means 'switch' user. We use the '-s' flag because the `homeassistant` user is a system user and doesn't have a default shell by default (to prevent attackers from being able to log in as that user).
+
+### {% linkable_title Step 4: Set up the virtualenv %}
+
+All this step does is stick a Python environment in the directory we're using. That's it. It's just a directory. There's nothing special about it, and it is entirely self-contained.
+
+It will include a `bin` directory, which will contain all the executables used in the virtualenv (including hass itself). It also includes a script called `activate` which we will use to activate the virtualenv.
+
+```bash
+$ virtualenv -p python3 /srv/homeassistant
+```
+
+### {% linkable_title Step 5: Activate the virtualenv %}
+
+```bash
+$ source /srv/homeassistant/bin/activate
+```
+
+After that, your prompt should include `(homeassistant)`.
+
+### {% linkable_title Step 6: Install Home Assistant %}
+
+Once your virtualenv has been activated, you don't need to `sudo` any of your `pip` commands. `pip` will be installing things in the virtualenv, which the `homeassistant` user has permission to modify.
+
+```bash
+(homeassistant)$ pip3 install --upgrade homeassistant
+```
+
+And that's it... you now have Home Assistant installed, and you can be sure that every bit of it is contained in `/srv/homeassistant`.
+
+### {% linkable_title Finally... Run Home Assistant %}
+
+There are two ways to launch Home Assistant. If you are **in** the virtualenv, you can just run `hass` and it will work as normal. If the virtualenv is not activated, you just use the `hass` executable in the `bin` directory mentioned earlier. There is one caveat... Because Home Assistant stores its configuration in the user's home directory, we need to be the user `homeassistant` user or specify the configuration with `-c`.
+
+```bash
+$ sudo -u homeassistant -H /srv/homeassistant/bin/hass
+```
+
+The `-H` flag is important. It sets the `$HOME` environment variable to `/home/homeassistant` so `hass` can find its configuration.
+
+### {% linkable_title Upgrading Home Assistant %}
+
+Upgrading Home Assistant is simple, just repeat steps 3, 5 and 6.
+
+### {% linkable_title Starting Home Assistant on boot %}
+
+The [autostart instructions](/getting-started/autostart/) will work just fine, just be sure to replace `/usr/bin/hass` with `/srv/homeassistant/bin/hass` and specify the `homeassistant` user where appropriate.
+
+### {% linkable_title Installing python-openzwave in a virtualenv %}
+
+If you want to use Z-Wave devices, you will need to install `python-openzwave` in your virtualenv. This requires a small tweak to the instructions in [the Z-Wave Getting Started documentation](/getting-started/z-wave/)
+
+Install the dependencies as normal (Note: you will need to do this as your normal user, since `homeassistant` isn't a sudoer).
+
+```bash
+$ sudo apt-get install cython3 libudev-dev python3-sphinx python3-setuptools git
+```
+
+Then, activate your virtualenv (steps 3 and 5 above) and upgrade cython.
+
+```bash
+(homeassistant)$ pip3 install --upgrade cython==0.24.1
+```
+
+Finally, get and install `python-openzwave`.
+
+```bash
+(homeassistant)$ mkdir /srv/homeassistant/src
+(homeassistant)$ cd /srv/homeassistant/src
+(homeassistant)$ git clone https://github.com/OpenZWave/python-openzwave.git
+(homeassistant)$ cd python-openzwave
+(homeassistant)$ git checkout python3
+(homeassistant)$ PYTHON_EXEC=`which python3` make build
+(homeassistant)$ PYTHON_EXEC=`which python3` make install
+```