From 4dea071ff836197842e246c4f4e6c309debe186a Mon Sep 17 00:00:00 2001 From: Ryan Kraus Date: Wed, 2 Sep 2015 02:23:51 -0400 Subject: [PATCH 1/5] Refactor Getting Started page. This commit is a large refactoring of the getting started page. This version contains only the information necessary to get off the ground and get your bearings. There is also one consistent flow on information rather than a spaghetti flow. Advanced installation details have been moved to their own page (Docker and daemons). Details about opening firewall ports have been expanded a bit and moved to the troubleshooting page. The install instructions contain details about all three install types (production, beta, and dev). --- sass/custom/_paulus.scss | 153 +++++---- source/getting-started/advanced.markdown | 104 ++++++ source/getting-started/index.markdown | 315 ++++-------------- .../getting-started/troubleshooting.markdown | 29 +- 4 files changed, 268 insertions(+), 333 deletions(-) create mode 100644 source/getting-started/advanced.markdown diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index a1f761d3932..2aadb83156f 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -102,7 +102,7 @@ h6:hover a.title-link { article.post, article.page, article.listing { img, table { border-radius: 3px; - box-shadow: rgba(0,0,0,0.06) 0 0 10px; + box-shadow: rgba(0,0,0,0.06) 0 0 10px; } img.no-shadow { @@ -120,7 +120,7 @@ article.post, article.page, article.listing { text-align: center; padding-bottom: 3px; font-size: .9rem; - box-shadow: rgba(0,0,0,0.06) 0 0 10px; + box-shadow: rgba(0,0,0,0.06) 0 0 10px; img { display: block; @@ -171,7 +171,7 @@ p.note { &.warning { background-color: #F7F9E1; - + &::before { background-color: rgb(187, 185, 13);; content: "\f071" " Warning " attr(data-title); @@ -180,80 +180,6 @@ p.note { } -.install-instructions-container { - #normal-install, #raspberry-install, #docker-install, .install-instructions { - display: none; - } - - label.menu-selector { - display: inline-block; - text-align: center; - padding: 20px; - white-space: nowrap; - border-bottom: 5px solid $grayLight; - transition: border-bottom-color .5s; - } - - label.menu-selector + label.menu-selector { - margin-left: 10px; - } - - #normal-install:checked ~ .menu-selector.normal, - #raspberry-install:checked ~ .menu-selector.raspberry, - #docker-install:checked ~ .menu-selector.docker - { - border-bottom-color: $blue; - } - - #normal-install:checked ~ .install-instructions.normal, - #raspberry-install:checked ~ .install-instructions.raspberry, - #docker-install:checked ~ .install-instructions.docker - { - display: block; - } - - .install-instructions { - margin-top: 30px; - } -} - -.prep-instructions-container { - #generic-prep, #fedora-prep, #centos-prep, .prep-instructions { - display: none; - } - - label.menu-selector { - display: inline-block; - text-align: center; - padding: 10px; - white-space: nowrap; - border-bottom: 2px solid $grayLight; - transition: border-bottom-color .5s; - } - - label.menu-selector + label.menu-selector { - margin-left: 10px; - } - - #generic-prep:checked ~ .menu-selector.generic, - #fedora-prep:checked ~ .menu-selector.fedora, - #centos-prep:checked ~ .menu-selector.centos - { - border-bottom-color: $blue; - } - - #generic-prep:checked ~ .prep-instructions.generic, - #fedora-prep:checked ~ .prep-instructions.fedora, - #centos-prep:checked ~ .prep-instructions.centos - { - display: block; - } - - .prep-instructions { - margin-top: 20px; - } -} - .post-instructions-container { #generic-post, #fedora-post, #debian-post, .post-instructions { display: none; @@ -292,3 +218,76 @@ p.note { } +.install-channels-container { + #prod-channel, #beta-channel, #dev-channel, .install-channels { + display: none; + } + + label.menu-selector { + display: inline-block; + text-align: center; + padding: 10px; + white-space: nowrap; + border-bottom: 2px solid $grayLight; + transition: border-bottom-color .5s; + } + + label.menu-selector + label.menu-selector { + margin-left: 10px; + } + + #prod-channel:checked ~ .menu-selector.prodchan, + #beta-channel:checked ~ .menu-selector.betachan, + #dev-channel:checked ~ .menu-selector.devchan + { + border-bottom-color: $blue; + } + + #prod-channel:checked ~ .install-channels.prodchan, + #beta-channel:checked ~ .install-channels.betachan, + #dev-channel:checked ~ .install-channels.devchan + { + display: block; + } + + .install-channels { + margin-top: 20px; + } +} + +.advanced-installs-container { + #docker-install, #debian-install, #fedora-install, .advanced-installs { + display: none; + } + + label.menu-selector { + display: inline-block; + text-align: center; + padding: 10px; + white-space: nowrap; + border-bottom: 2px solid $grayLight; + transition: border-bottom-color .5s; + } + + label.menu-selector + label.menu-selector { + margin-left: 10px; + } + + #docker-install:checked ~ .menu-selector.docker, + #debian-install:checked ~ .menu-selector.debian, + #fedora-install:checked ~ .menu-selector.fedora + { + border-bottom-color: $blue; + } + + #docker-install:checked ~ .advanced-installs.docker, + #debian-install:checked ~ .advanced-installs.debian, + #fedora-install:checked ~ .advanced-installs.fedora + { + display: block; + } + + .advanced-installs { + margin-top: 20px; + } +} diff --git a/source/getting-started/advanced.markdown b/source/getting-started/advanced.markdown new file mode 100644 index 00000000000..c0ac7592522 --- /dev/null +++ b/source/getting-started/advanced.markdown @@ -0,0 +1,104 @@ +--- +layout: page +title: "Advanced Installation" +description: "Brief advanced installation tutorials." +date: 2015-9-1 22:57 +sidebar: false +comments: false +sharing: true +footer: true +--- + +Here are some general tutorials on how to setup some of the more advanced deployments that are frequently requested. + +
+ + + + + + + +
+**Docker Deployment** +

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:

+ +```bash +docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant +``` + +

This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

+ +

+When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone) +

+
+ +
+**Debian Deamon** +

Debian based systems, including Ubuntu and Raspbian for the Raspberry Pi use an application called Init to manage daemon services. Init will launch init scripts that are located in the directory /etc/init.d/. A sample init script for Debian based systems is maintained in this project.

+ +

To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands: +```bash +sudo service hass-daemon start +sudo service hass-daemon stop +``` +

+ +

When running Home Assistant with this script, the configuration directory will be located at /var/opt/homeassistant. This directory will contain a verbose log rather than simply an error log.

+ +

When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.

+
+ +
+**Fedora Daemon** +

If you want that Home Assistant is lauched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.

+ + + + +```bash +su -c 'cat <> /lib/systemd/system/home-assistant.service +[Unit] +Description=Home Assistant +After=network.target + +[Service] +Type=simple +ExecStart=hass + +[Install] +WantedBy=multi-user.target +EOF' +``` + +

You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.

+ +```bash +sudo systemctl --system daemon-reload +sudo systemctl enable home-assistant +sudo systemctl start home-assistant +``` + +

If everything went well, sudo systemctl start home-assistant should give you a positive feedback.

+ +```bash +$ sudo systemctl status home-assistant -l +● home-assistant.service - Home Assistant + Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled) + Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago + Main PID: 8557 (python3.4) + CGroup: /system.slice/home-assistant.service + └─8557 /usr/bin/python3.4 -m homeassistant +[...] +``` + +

To get Home Assistant's logging output, simple use journalctl.

+ +```bash +sudo journalctl -f -u home-assistant +``` +
+ +###[« Back to Getting Started](/getting-started/index.html) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 044e632db49..6be4f213ae6 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -9,284 +9,97 @@ sharing: true footer: true --- -
- - - - - - -
+

Requirements

+

Home Assistant requires at least Python 3.4. For the Raspberry Pi, install instructions can be found here. Other systems generally have this bundled or contain easy to install packages.

-

Preparation

- -
- - - - - - - - -
-Installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 installed and execute the following code in a console: - - -
- -
-

The preparation of a Fedora 22 host will only take a couple of minutes. First install Python 3.4 and the other needed packages out of the Fedora Package Collection. This ensure that you receive updates in the future.

- -

-It's assumed that your user has an entry in the sudoers file. Otherwise, run the commands which needs more privileges as root. -

+

To ensure Python 3.4 is installed, type the following command into the console:

```bash -sudo dnf -y install python3 python3-devel gcc +python3 --version ``` -
- -
- -

CentOS is providing longtime support and often not shipping the latest release of a software component. To run, Python 3.x on CentOS Software Collections needs to be activated.

- -
Step 1. Install the tools for the Software Collection
- -```bash -sudo yum -y install scl-utils -``` - -
Step 2. Make the repository available.
- -```bash -sudo yum -y install https://www.softwarecollections.org/en/scls/rhscl/rh-python34/epel-7-x86_64/download/rhscl-rh-python34-epel-7-x86_64.noarch.rpm -``` - -
Step 3. Install Python 3.x
- -```bash -sudo yum -y install rh-python34 -``` - -
Step 4. Start using software collections:
- -```bash -scl enable rh-python34 bash -``` - -
- -
- -
-

Installation

+
+ + + + + + -

+

+

Installing from the production channel is fast, easy, and will provide you with access to the newest stable builds. This is recommended for most users. To install, execute the following code in a console:

```bash pip3 install homeassistant hass --open-ui ``` -

-

Running these commands will:

+

Running these commands will:

  1. Install Home Assistant
  2. Launch Home Assistant and serve web interface on http://localhost:8123
    3. -
-
- - -

Post-Installation

- -
- - - - - - - - -
-

There is nothing else to do. If you run into any issues, please see the troubleshooting page.

- -

If you want to see what Home Assistant can do, you can start the demo mode by running hass --demo-mode.

- -

In the future, if you want to update to the latest version, run pip3 install --upgrade home-assistant.

- -
- -
-

By default, the access to port 8123 is not allowed. If you want to allow other hosts in your local network access, open port 8123.

- +

+

When new stable versions are released, you can upgrade to newest version by typing the following into a console:

```bash -sudo firewall-cmd --permanent --add-port=8123/tcp -sudo firewall-cmd --reload +pip3 install --upgrade homeassistant ``` -

Home Assistant will serve its web interface on http://[IP address of the host]:8123.

- -

If you want that Home Assistant is lauched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.

- - - - -```bash -su -c 'cat <> /lib/systemd/system/home-assistant.service -[Unit] -Description=Home Assistant -After=network.target - -[Service] -Type=simple -ExecStart=/usr/bin/python3.4 -m homeassistant - -[Install] -WantedBy=multi-user.target -EOF' -``` - -

You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.

- -```bash -sudo systemctl --system daemon-reload -sudo systemctl enable home-assistant -sudo systemctl start home-assistant -``` - -

If everything went well, sudo systemctl start home-assistant should give you a positive feedback.

- -```bash -$ sudo systemctl status home-assistant -l -● home-assistant.service - Home Assistant - Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled) - Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago - Main PID: 8557 (python3.4) - CGroup: /system.slice/home-assistant.service - └─8557 /usr/bin/python3.4 -m homeassistant -[...] -``` - -

To get Home Assistant's logging output, simple use journalctl.

- -```bash -sudo journalctl -f -u home-assistant -``` - -

In the future, if you want to update to the latest version, run pip3 install --upgrade home-assistant.

- -

-Those instructions were written for Fedora 22 Server and Workstation. They may work for Cloud flavor as well but this was not tested. -

- - -
- -
- -

Coming soon...

- - -
+
+

The beta channel will provide you with newer features sooner but at the risk of reduced stability. The brave and curious are welcomed here. To install, execute the following code in a console:

+```bash +pip3 install --pre homeassistant +hass --open-ui +``` +

Running these commands will: +

    +
  1. Install Home Assistant
    2. +
  2. Launch Home Assistant and serve web interface on http://localhost:8123
    3. +

+

When new a new release candidate, alpha, or beta version is released, you can upgrade to newest version by typing the following into a console:

+```bash +pip3 install --pre --upgrade homeassistant +```
-
- - -
- - -
-

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:

- -```bash -docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant -``` - -

This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

- -

-When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone) -

- -
- - -
- -

Home Assistant uses Python 3.4. This makes installation on a Raspberry Pi a bit more difficult as it is not available in the package repository. Please follow the following instructions to get it up and running.

- -

Step 1. Install pyenv

- -```bash -curl -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash -``` - -

After the installation is done, run:

- -```bash -nano ~/.bashrc -``` - -

Then add these lines to the end of the file and save:

-``` -export PATH="$HOME/.pyenv/bin:$PATH" -eval "$(pyenv init -)" -eval "$(pyenv virtualenv-init -)" -``` - -
Step 2. Install requirements
- -```bash -sudo apt-get install python3-dev -sudo apt-get install libsqlite3-dev libreadline-dev libbz2-dev -``` - -

Log out and then back in so your bashrc is reloaded.

- -

-NOTE: the rest of the commands are not being run as sudo and will install python etc under you user's home directory. -

- -

Step 3. Install python 3.4.2 (this will take a few hours)

- -```bash -pyenv install 3.4.2 -``` - -

Step 4. Create Python Virtual Environment

-```bash -pyenv virtualenv 3.4.2 homeassistant -``` - -

Step 5. Set the virtual environment

+
+

The development channel provides builds that are on the bleeding edge. This builds have not been fully tested or used. This is best for potential contributors and tinkerers. Subscribing to this channel is not for the faint of heart and requires significant knowledge of Git and Python.

```bash +# Clone repo from git, you may want to use your own fork +git clone --recursive https://github.com/balloob/home-assistant.git cd home-assistant -pyenv local homeassistant +# You may want to switch to a virtual environment here +# Install Home Assistant in development mode +python3 setup.py develop +# Optionally pre-emptively install all possible dependencies +pip3 install -r requirements_all.txt ``` - -

Step 6. Install Home Assistant

+

To keep up-to-date with the development channel, you will have to fetch and merge from the dev branch in the head repository. Be careful when doing this.

```bash -pip3 install homeassistant +git fetch balloob +git merge remotes/balloob/dev ``` - -

Step 7. Start it up

-```bash -hass -``` - -

It will be up and running on port 8123

- -

In the future, if you want to update to the latest version, run pip3 install --upgrade home-assistant.

-
-
+
+ + +

Troubleshooting

+ +

If you run into any issues, please see the troubleshooting page. It contains solutions to many of the common issues.

+ +

For additional help, in addition to this site, there are three sources: +

+

+ + +

What's Next

+

If you want to see what Home Assistant can do, you can start the demo mode by running hass --demo-mode. Home Assistant has a few other command line flags that can be displayed by running hass --help.

+

From here you may now start configuring Home Assistant to your liking. For more advanced users, the advanced configuration page contains brief tutorials on creating more advanced installations such as installing daemons and using Docker.

+ ###[Next step: configuring Home Assistant »](/getting-started/configuration.html) - diff --git a/source/getting-started/troubleshooting.markdown b/source/getting-started/troubleshooting.markdown index b3588e679d9..3d1e7a0f629 100644 --- a/source/getting-started/troubleshooting.markdown +++ b/source/getting-started/troubleshooting.markdown @@ -17,7 +17,7 @@ This utility should have been installed as part of the Python 3.4 installation. is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/). -If you are to succesfully run `python3 --version` but not `pip3`, run the following command instead +If you are able to successfully run `python3 --version` but not `pip3`, run the following command instead to install Home Assistant: `python3 -m pip install homeassistant`. **No module named pip**
@@ -27,8 +27,27 @@ by some distributions. If you are unable to run `python3 -m pip --version` you c `python3 get-pip.py`. **No access to the frontend**
-In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host are very limited. -This means that you can't access the Home Assistant Frontend that is running on a host in your -network. Check the Post-installation section on the [Getting started](/getting-started/) page and -follow the instruction that match your distribution to allow access to port 8123. +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 OSX machines may also have issues with this. +To fix this you will need to open your machine's firewall for TCP traffic over 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](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7) and [Mac OSX](https://support.apple.com/en-us/HT201642) have good instructions posted. + +For firewalld systems (Fedora, 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 (usually the default): +```bash +iptables -I INPUT -p tcp --dport 8123 -j ACCEPT +iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere +``` +###[« Back to Getting Started](/getting-started/index.html) From 46c68f411b2ca52c853f5b5acedd9d4918c21176 Mon Sep 17 00:00:00 2001 From: Ryan Kraus Date: Wed, 2 Sep 2015 23:32:50 -0400 Subject: [PATCH 2/5] Another reorganization of the Getting Started page. --- sass/custom/_paulus.scss | 66 +++---------- source/getting-started/advanced.markdown | 19 +--- source/getting-started/index.markdown | 113 +++++++++++------------ 3 files changed, 69 insertions(+), 129 deletions(-) diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index 2aadb83156f..e7bf78e4738 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -180,17 +180,17 @@ p.note { } -.post-instructions-container { - #generic-post, #fedora-post, #debian-post, .post-instructions { +.install-instructions-container { + #normal-install, #raspberry-install, #docker-install, .install-instructions { display: none; } label.menu-selector { display: inline-block; text-align: center; - padding: 10px; + padding: 20px; white-space: nowrap; - border-bottom: 2px solid $grayLight; + border-bottom: 5px solid $grayLight; transition: border-bottom-color .5s; } @@ -198,65 +198,27 @@ p.note { margin-left: 10px; } - #generic-post:checked ~ .menu-selector.generic-post, - #fedora-post:checked ~ .menu-selector.fedora-post, - #debian-post:checked ~ .menu-selector.debian-post + #normal-install:checked ~ .menu-selector.normal, + #raspberry-install:checked ~ .menu-selector.raspberry, + #docker-install:checked ~ .menu-selector.docker { border-bottom-color: $blue; } - #generic-post:checked ~ .post-instructions.generic-post, - #fedora-post:checked ~ .post-instructions.fedora-post, - #debian-post:checked ~ .post-instructions.debian-post + #normal-install:checked ~ .install-instructions.normal, + #raspberry-install:checked ~ .install-instructions.raspberry, + #docker-install:checked ~ .install-instructions.docker { display: block; } - .post-instructions { - margin-top: 20px; - } - -} - -.install-channels-container { - #prod-channel, #beta-channel, #dev-channel, .install-channels { - display: none; - } - - label.menu-selector { - display: inline-block; - text-align: center; - padding: 10px; - white-space: nowrap; - border-bottom: 2px solid $grayLight; - transition: border-bottom-color .5s; - } - - label.menu-selector + label.menu-selector { - margin-left: 10px; - } - - #prod-channel:checked ~ .menu-selector.prodchan, - #beta-channel:checked ~ .menu-selector.betachan, - #dev-channel:checked ~ .menu-selector.devchan - { - border-bottom-color: $blue; - } - - #prod-channel:checked ~ .install-channels.prodchan, - #beta-channel:checked ~ .install-channels.betachan, - #dev-channel:checked ~ .install-channels.devchan - { - display: block; - } - - .install-channels { - margin-top: 20px; + .install-instructions { + margin-top: 30px; } } .advanced-installs-container { - #docker-install, #debian-install, #fedora-install, .advanced-installs { + #debian-install, #fedora-install, .advanced-installs { display: none; } @@ -273,14 +235,12 @@ p.note { margin-left: 10px; } - #docker-install:checked ~ .menu-selector.docker, #debian-install:checked ~ .menu-selector.debian, #fedora-install:checked ~ .menu-selector.fedora { border-bottom-color: $blue; } - #docker-install:checked ~ .advanced-installs.docker, #debian-install:checked ~ .advanced-installs.debian, #fedora-install:checked ~ .advanced-installs.fedora { diff --git a/source/getting-started/advanced.markdown b/source/getting-started/advanced.markdown index c0ac7592522..24c45d73377 100644 --- a/source/getting-started/advanced.markdown +++ b/source/getting-started/advanced.markdown @@ -12,28 +12,11 @@ footer: true Here are some general tutorials on how to setup some of the more advanced deployments that are frequently requested.
- - + - -
-**Docker Deployment** -

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:

- -```bash -docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant -``` - -

This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

- -

-When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone) -

-
-
**Debian Deamon**

Debian based systems, including Ubuntu and Raspbian for the Raspberry Pi use an application called Init to manage daemon services. Init will launch init scripts that are located in the directory /etc/init.d/. A sample init script for Debian based systems is maintained in this project.

diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 6be4f213ae6..f2f2cbfdf62 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -9,79 +9,67 @@ sharing: true footer: true --- -

Requirements

-

Home Assistant requires at least Python 3.4. For the Raspberry Pi, install instructions can be found here. Other systems generally have this bundled or contain easy to install packages.

- -

To ensure Python 3.4 is installed, type the following command into the console:

- -```bash -python3 --version -``` +
+ + + + + +

Installation

-
- - - - - - -
-

Installing from the production channel is fast, easy, and will provide you with access to the newest stable builds. This is recommended for most users. To install, execute the following code in a console:

+ +
+Installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 installed and execute the following code in a console: + +

```bash pip3 install homeassistant hass --open-ui ``` -

Running these commands will: +

+

Running these commands will:

  1. Install Home Assistant
    2. -
  2. Launch Home Assistant and serve web interface on http://localhost:8123
    3. -

-

When new stable versions are released, you can upgrade to newest version by typing the following into a console:

-```bash -pip3 install --upgrade homeassistant -``` -
+
  • Launch Home Assistant and serve web interface on http://localhost:8123
    • + +
    + + +
    +

    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:

    -
    -

    The beta channel will provide you with newer features sooner but at the risk of reduced stability. The brave and curious are welcomed here. To install, execute the following code in a console:

    ```bash -pip3 install --pre homeassistant +docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant +``` + +

    This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

    + +

    +When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone) +

    +
    + + +
    +

    Home Assistant uses Python 3.4 which is not shipped with the current Raspbian distibution for the Raspberry Pi. Before installing Home Assistant, you will have to target="_blank"install Python 3.4. + +Once that is complete, installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 installed and execute the following code in a console: + +

    +```bash +pip3 install homeassistant hass --open-ui ``` -

    Running these commands will: +

    +

    Running these commands will:

    1. Install Home Assistant
      2. -
    2. Launch Home Assistant and serve web interface on http://localhost:8123
      3. -

    -

    When new a new release candidate, alpha, or beta version is released, you can upgrade to newest version by typing the following into a console:

    -```bash -pip3 install --pre --upgrade homeassistant -``` -
    - -
    -

    The development channel provides builds that are on the bleeding edge. This builds have not been fully tested or used. This is best for potential contributors and tinkerers. Subscribing to this channel is not for the faint of heart and requires significant knowledge of Git and Python.

    -```bash -# Clone repo from git, you may want to use your own fork -git clone --recursive https://github.com/balloob/home-assistant.git -cd home-assistant -# You may want to switch to a virtual environment here -# Install Home Assistant in development mode -python3 setup.py develop -# Optionally pre-emptively install all possible dependencies -pip3 install -r requirements_all.txt -``` -

    To keep up-to-date with the development channel, you will have to fetch and merge from the dev branch in the head repository. Be careful when doing this.

    -```bash -git fetch balloob -git merge remotes/balloob/dev -``` -
    - -
    +
  • Launch Home Assistant and serve web interface on http://localhost:8123
    • + +

    Troubleshooting

    @@ -96,10 +84,19 @@ git merge remotes/balloob/dev

    +

    Staying Up to Date

    +

    In order to update Home Assistant to the latest stable release, simply type the following into a console:

    +```bash +pip install --upgrade homeassistant +``` +

    If you would like to stay up to date with the newest unstable builds (alphas, betas, and release candidates), use this command:

    +```bash +pip install --upgrade --pre homeassistant +```

    What's Next

    If you want to see what Home Assistant can do, you can start the demo mode by running hass --demo-mode. Home Assistant has a few other command line flags that can be displayed by running hass --help.

    -

    From here you may now start configuring Home Assistant to your liking. For more advanced users, the advanced configuration page contains brief tutorials on creating more advanced installations such as installing daemons and using Docker.

    +

    From here you may now start configuring Home Assistant to your liking. For more advanced users, the advanced configuration page contains brief tutorials on creating more advanced installations.

    ###[Next step: configuring Home Assistant »](/getting-started/configuration.html) From db3614592866be575558a7a3c031445aa0d128e0 Mon Sep 17 00:00:00 2001 From: Ryan Kraus Date: Wed, 2 Sep 2015 23:35:15 -0400 Subject: [PATCH 3/5] Fixed small typo on getting started page. --- source/getting-started/index.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index f2f2cbfdf62..340a2ce71c6 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -54,7 +54,7 @@ When using boot2docker on OS X you are unable to map the local time to your Dock
    -

    Home Assistant uses Python 3.4 which is not shipped with the current Raspbian distibution for the Raspberry Pi. Before installing Home Assistant, you will have to target="_blank"install Python 3.4. +

    Home Assistant uses Python 3.4 which is not shipped with the current Raspbian distibution for the Raspberry Pi. Before installing Home Assistant, you will have to install Python 3.4. Once that is complete, installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 installed and execute the following code in a console: From 9d3ea63632339042a01f2ecf25ac14093244b6bc Mon Sep 17 00:00:00 2001 From: Ryan Kraus Date: Wed, 2 Sep 2015 23:41:59 -0400 Subject: [PATCH 4/5] Escaped double dashes on getting started page. --- source/getting-started/index.markdown | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 340a2ce71c6..70f072a9a4a 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -27,7 +27,7 @@ Installing and running Home Assistant on your local machine is easy. Make sure y

    ```bash pip3 install homeassistant -hass --open-ui +hass \-\-open-ui ```

    Running these commands will:

    @@ -42,7 +42,7 @@ hass --open-ui

    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:

    ```bash -docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant +docker run -d \-\-name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro \-\-net=host balloob/home-assistant ```

    This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

    @@ -61,7 +61,7 @@ Once that is complete, installing and running Home Assistant on your local machi

    ```bash pip3 install homeassistant -hass --open-ui +hass \-\-open-ui ```

    Running these commands will:

    @@ -87,15 +87,15 @@ hass --open-ui

    Staying Up to Date

    In order to update Home Assistant to the latest stable release, simply type the following into a console:

    ```bash -pip install --upgrade homeassistant +pip install \-\-upgrade homeassistant ```

    If you would like to stay up to date with the newest unstable builds (alphas, betas, and release candidates), use this command:

    ```bash -pip install --upgrade --pre homeassistant +pip install \-\-upgrade \-\-pre homeassistant ```

    What's Next

    -

    If you want to see what Home Assistant can do, you can start the demo mode by running hass --demo-mode. Home Assistant has a few other command line flags that can be displayed by running hass --help.

    +

    If you want to see what Home Assistant can do, you can start the demo mode by running hass \-\-demo-mode. Home Assistant has a few other command line flags that can be displayed by running hass \-\-help.

    From here you may now start configuring Home Assistant to your liking. For more advanced users, the advanced configuration page contains brief tutorials on creating more advanced installations.

    From 7ba2a552328911e1a4f7d9220b884dd82dbe79e3 Mon Sep 17 00:00:00 2001 From: Ryan Kraus Date: Sat, 5 Sep 2015 05:40:45 -0400 Subject: [PATCH 5/5] Updated Advanced Install page to focus on daemon managers. The advanced install page was reworded to be organized by daemon manager rather than Linux distribution. Some wording changes were made on the Getting Started page. --- sass/custom/_paulus.scss | 17 ++++---- source/getting-started/advanced.markdown | 54 +++++++++++++++--------- source/getting-started/index.markdown | 4 +- 3 files changed, 44 insertions(+), 31 deletions(-) diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index e7bf78e4738..a52577199fa 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -218,16 +218,17 @@ p.note { } .advanced-installs-container { - #debian-install, #fedora-install, .advanced-installs { + + #upstart-install, #systemd-install, .advanced-installs { display: none; } label.menu-selector { display: inline-block; text-align: center; - padding: 10px; + padding: 20px; white-space: nowrap; - border-bottom: 2px solid $grayLight; + border-bottom: 5px solid $grayLight; transition: border-bottom-color .5s; } @@ -235,19 +236,19 @@ p.note { margin-left: 10px; } - #debian-install:checked ~ .menu-selector.debian, - #fedora-install:checked ~ .menu-selector.fedora + #upstart-install:checked ~ .menu-selector.upstart, + #systemd-install:checked ~ .menu-selector.systemd { border-bottom-color: $blue; } - #debian-install:checked ~ .advanced-installs.debian, - #fedora-install:checked ~ .advanced-installs.fedora + #upstart-install:checked ~ .advanced-installs.upstart, + #systemd-install:checked ~ .advanced-installs.systemd { display: block; } .advanced-installs { - margin-top: 20px; + margin-top: 30px; } } diff --git a/source/getting-started/advanced.markdown b/source/getting-started/advanced.markdown index 24c45d73377..bf2cf5698d9 100644 --- a/source/getting-started/advanced.markdown +++ b/source/getting-started/advanced.markdown @@ -12,34 +12,46 @@ footer: true Here are some general tutorials on how to setup some of the more advanced deployments that are frequently requested.
    - - - - + + + + -
    -**Debian Deamon** -

    Debian based systems, including Ubuntu and Raspbian for the Raspberry Pi use an application called Init to manage daemon services. Init will launch init scripts that are located in the directory /etc/init.d/. A sample init script for Debian based systems is maintained in this project.

    -

    To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands: +

    +Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command: + +```bash +ps -p 1 -o comm= +``` + +If the preceding command returns the string `init`, you are likely using Upstart. + +Upstart will launch init scripts that are located in the directory /etc/init.d/. A sample init script for systems using Upstart is maintained by this project. + +To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands: ```bash sudo service hass-daemon start sudo service hass-daemon stop ``` -

    -

    When running Home Assistant with this script, the configuration directory will be located at /var/opt/homeassistant. This directory will contain a verbose log rather than simply an error log.

    +When running Home Assistant with this script, the configuration directory will be located at /var/opt/homeassistant. This directory will contain a verbose log rather than simply an error log. -

    When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.

    -
    +When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document. +
    -
    -**Fedora Daemon** -

    If you want that Home Assistant is lauched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.

    - +
    +Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command: + +```bash +ps -p 1 -o comm= +``` + +If the preceding command returns the string `systemd`, you are likely using systemd. + +If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd. ```bash su -c 'cat <> /lib/systemd/system/home-assistant.service @@ -56,7 +68,7 @@ WantedBy=multi-user.target EOF' ``` -

    You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.

    +You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that. ```bash sudo systemctl --system daemon-reload @@ -64,7 +76,7 @@ sudo systemctl enable home-assistant sudo systemctl start home-assistant ``` -

    If everything went well, sudo systemctl start home-assistant should give you a positive feedback.

    +If everything went well, sudo systemctl start home-assistant should give you a positive feedback. ```bash $ sudo systemctl status home-assistant -l @@ -77,11 +89,11 @@ $ sudo systemctl status home-assistant -l [...] ``` -

    To get Home Assistant's logging output, simple use journalctl.

    +To get Home Assistant's logging output, simple use journalctl. ```bash sudo journalctl -f -u home-assistant ``` -
    +
    ###[« Back to Getting Started](/getting-started/index.html) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 70f072a9a4a..bb93f58ee07 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -74,7 +74,7 @@ hass \-\-open-ui

    Troubleshooting

    -

    If you run into any issues, please see the troubleshooting page. It contains solutions to many of the common issues.

    +

    If you run into any issues, please see the troubleshooting page. It contains solutions to many of the more commonly encountered issues.

    For additional help, in addition to this site, there are three sources:

      @@ -99,4 +99,4 @@ pip install \-\-upgrade \-\-pre homeassistant

      From here you may now start configuring Home Assistant to your liking. For more advanced users, the advanced configuration page contains brief tutorials on creating more advanced installations.

      -###[Next step: configuring Home Assistant »](/getting-started/configuration.html) +###[Next step: Configuring Home Assistant »](/getting-started/configuration.html)