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
This commit is contained in:
Fabian Affolter
GitHub
parent
0677895b5b
commit
481320128f
138 changed files with 1309 additions and 909 deletions
138
source/_docs/autostart/init.d.markdown
Normal file
138
source/_docs/autostart/init.d.markdown
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Autostart using init.d"
|
||||
description: "Documentation about setting up Home Assistant as a daemon running under init.d."
|
||||
release_date: 2016-12-02 15:00:00 -0700
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
redirect_from: /getting-started/autostart-init.d/
|
||||
---
|
||||
|
||||
Home Assistant can run as a daemon within init.d with the script below.
|
||||
|
||||
### {% linkable_title 1. Copy script %}
|
||||
|
||||
Copy the script at the end of this page to `/etc/init.d/hass-daemon`.
|
||||
|
||||
After that, set the script to be executable:
|
||||
|
||||
```bash
|
||||
$ sudo chmod +x /etc/init.d/hass-daemon
|
||||
```
|
||||
|
||||
### {% linkable_title 2. Select a user. %}
|
||||
|
||||
Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute hass.
|
||||
|
||||
### {% linkable_title 3. Register the daemon with Linux %}
|
||||
|
||||
```bash
|
||||
$ sudo update-rc.d hass-daemon defaults
|
||||
```
|
||||
|
||||
### {% linkable_title 4. Install this service %}
|
||||
|
||||
```bash
|
||||
$ sudo service hass-daemon install
|
||||
```
|
||||
|
||||
### {% linkable_title 5. Restart Machine %}
|
||||
|
||||
That's it. Restart your machine and Home Assistant should start automatically.
|
||||
|
||||
If HA does not start, check the log file output for errors at `/var/opt/homeassistant/home-assistant.log`
|
||||
|
||||
### {% linkable_title Extra: Running commands before hass executes %}
|
||||
|
||||
If any commands need to run before executing hass (like loading a virutal environment), put them in PRE_EXEC. This command must end with a semicolon.
|
||||
|
||||
### {% linkable_title Daemon script %}
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
### BEGIN INIT INFO
|
||||
# Provides: hass
|
||||
# Required-Start: $local_fs $network $named $time $syslog
|
||||
# Required-Stop: $local_fs $network $named $time $syslog
|
||||
# Default-Start: 2 3 4 5
|
||||
# Default-Stop: 0 1 6
|
||||
# Description: Home\ Assistant
|
||||
### END INIT INFO
|
||||
|
||||
# /etc/init.d Service Script for Home Assistant
|
||||
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
|
||||
PRE_EXEC=""
|
||||
RUN_AS="USER"
|
||||
PID_FILE="/var/run/hass.pid"
|
||||
CONFIG_DIR="/var/opt/homeassistant"
|
||||
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --daemon"
|
||||
REDIRECT="> $CONFIG_DIR/home-assistant.log 2>&1"
|
||||
|
||||
start() {
|
||||
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
|
||||
echo 'Service already running' >&2
|
||||
return 1
|
||||
fi
|
||||
echo 'Starting service…' >&2
|
||||
local CMD="$PRE_EXEC hass $FLAGS $REDIRECT;"
|
||||
su -c "$CMD" $RUN_AS
|
||||
echo 'Service started' >&2
|
||||
}
|
||||
|
||||
stop() {
|
||||
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
|
||||
echo 'Service not running' >&2
|
||||
return 1
|
||||
fi
|
||||
echo 'Stopping service…' >&2
|
||||
kill $(cat "$PID_FILE")
|
||||
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
|
||||
echo 'Service stopped' >&2
|
||||
}
|
||||
|
||||
install() {
|
||||
echo "Installing Home Assistant Daemon (hass-daemon)"
|
||||
echo "999999" > $PID_FILE
|
||||
chown $RUN_AS $PID_FILE
|
||||
mkdir -p $CONFIG_DIR
|
||||
chown $RUN_AS $CONFIG_DIR
|
||||
}
|
||||
|
||||
uninstall() {
|
||||
echo -n "Are you really sure you want to uninstall this service? That cannot be undone. [yes|No] "
|
||||
local SURE
|
||||
read SURE
|
||||
if [ "$SURE" = "yes" ]; then
|
||||
stop
|
||||
rm -fv "$PID_FILE"
|
||||
echo "Notice: The config directory has not been removed"
|
||||
echo $CONFIG_DIR
|
||||
update-rc.d -f hass-daemon remove
|
||||
rm -fv "$0"
|
||||
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
|
||||
fi
|
||||
}
|
||||
|
||||
case "$1" in
|
||||
start)
|
||||
start
|
||||
;;
|
||||
stop)
|
||||
stop
|
||||
;;
|
||||
install)
|
||||
install
|
||||
;;
|
||||
uninstall)
|
||||
uninstall
|
||||
;;
|
||||
restart)
|
||||
stop
|
||||
start
|
||||
;;
|
||||
*)
|
||||
echo "Usage: $0 {start|stop|restart|install|uninstall}"
|
||||
esac
|
||||
```
|
||||
32
source/_docs/autostart/macos.markdown
Normal file
32
source/_docs/autostart/macos.markdown
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Autostart on macOS"
|
||||
description: "Instructions how to setup Home Assistant to launch on Apple macOS."
|
||||
date: 2015-9-1 22:57
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
redirect_from: /getting-started/autostart-macos/
|
||||
---
|
||||
|
||||
Setting up Home Assistant to run as a background service is simple; macOS will start Home Assistant on boot and make sure it's always running.
|
||||
|
||||
To get Home Assistant installed as a background service, run:
|
||||
|
||||
|
||||
```bash
|
||||
$ hass --script macos install
|
||||
|
||||
Home Assistant has been installed. Open it here: http://localhost:8123
|
||||
```
|
||||
|
||||
Home Assistant will log to `~/Library/Logs/homeassistant.log`
|
||||
|
||||
To uninstall the service, run:
|
||||
|
||||
```bash
|
||||
$ hass --script macos uninstall
|
||||
|
||||
Home Assistant has been uninstalled.
|
||||
```
|
||||
50
source/_docs/autostart/synology.markdown
Normal file
50
source/_docs/autostart/synology.markdown
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Autostart on Synology NAS boot"
|
||||
description: "Instructions how to setup Home Assistant to launch on boot on Synology NAS."
|
||||
date: 2015-9-1 22:57
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
redirect_from: /getting-started/autostart-synology/
|
||||
---
|
||||
|
||||
To get Home Assistant to automatically start when you boot your Synology NAS:
|
||||
|
||||
SSH into your synology & login as admin or root
|
||||
|
||||
```bash
|
||||
$ cd /volume1/homeassistant
|
||||
```
|
||||
|
||||
Create "homeassistant.conf" file using the following code
|
||||
|
||||
```bash
|
||||
# only start this service after the httpd user process has started
|
||||
start on started httpd-user
|
||||
|
||||
# stop the service gracefully if the runlevel changes to 'reboot'
|
||||
stop on runlevel [06]
|
||||
|
||||
# run the scripts as the 'http' user. Running as root (the default) is a bad ide
|
||||
#setuid admin
|
||||
|
||||
# exec the process. Use fully formed path names so that there is no reliance on
|
||||
# the 'www' file is a node.js script which starts the foobar application.
|
||||
exec /bin/sh /volume1/homeassistant/hass-daemon start
|
||||
```
|
||||
|
||||
Register the autostart
|
||||
|
||||
```bash
|
||||
$ ln -s homeassistant-conf /etc/init/homeassistant-conf
|
||||
```
|
||||
|
||||
Make the relevant files executable:
|
||||
|
||||
```bash
|
||||
$ chmod -r 777 /etc/init/homeassistant-conf
|
||||
```
|
||||
|
||||
That's it - reboot your NAS and Home Assistant should automatically start
|
||||
108
source/_docs/autostart/systemd.markdown
Normal file
108
source/_docs/autostart/systemd.markdown
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Autostart using systemd"
|
||||
description: "Instructions how to setup Home Assistant to launch on boot using systemd."
|
||||
date: 2015-9-1 22:57
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
redirect_from: /getting-started/autostart-systemd/
|
||||
---
|
||||
|
||||
Newer linux distributions are trending towards using `systemd` for managing daemons. Typically, systems based on Fedora, ArchLinux, 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`. If you are using a Raspberry Pi with Raspbian then replace the `[your user]` with `pi` otherwise use your user you want to run Home Assistant. `ExecStart` contains the path to `hass` and this may vary. Check with `whereis hass` for the location.
|
||||
|
||||
```bash
|
||||
$ su -c 'cat <<EOF >> /etc/systemd/system/home-assistant@.service
|
||||
[Unit]
|
||||
Description=Home Assistant
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=%i
|
||||
ExecStart=/usr/bin/hass
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF'
|
||||
```
|
||||
|
||||
If you've setup Home Assistant in `virtualenv` following our [python installation guide](https://home-assistant.io/getting-started/installation-virtualenv/) or [manual installation guide for raspberry pi](https://home-assistant.io/getting-started/installation-raspberry-pi/), the following template should work for you.
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=Home Assistant
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=homeassistant
|
||||
# Make sure the virtualenv Python binary is used
|
||||
Environment=VIRTUAL_ENV="/srv/homeassistant"
|
||||
Environment=PATH="$VIRTUAL_ENV/bin:$PATH"
|
||||
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
If you want to use docker, the following template should work for you.
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=Home Assistant
|
||||
Requires=docker.service
|
||||
After=docker.service
|
||||
|
||||
[Service]
|
||||
Restart=always
|
||||
RestartSec=3
|
||||
ExecStart=/usr/bin/docker run --name="home-assistant-%i" -v /home/%i/.homeassistant/:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
|
||||
ExecStop=/usr/bin/docker stop -t 2 home-assistant-%i
|
||||
ExecStopPost=/usr/bin/docker rm -f home-assistant-%i
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
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@[your user]
|
||||
$ sudo systemctl start home-assistant@[your user]
|
||||
```
|
||||
|
||||
If everything went well, `sudo systemctl start home-assistant@[your user]` should give you a positive feedback.
|
||||
|
||||
```bash
|
||||
$ sudo systemctl status home-assistant@[your user] -l
|
||||
● home-assistant@fab.service - Home Assistant for [your user]
|
||||
Loaded: loaded (/etc/systemd/system/home-assistant@[your user].service; enabled; vendor preset: disabled)
|
||||
Active: active (running) since Sat 2016-03-26 12:26:06 CET; 13min ago
|
||||
Main PID: 30422 (hass)
|
||||
CGroup: /system.slice/system-home\x2dassistant.slice/home-assistant@[your user].service
|
||||
├─30422 /usr/bin/python3 /usr/bin/hass
|
||||
└─30426 /usr/bin/python3 /usr/bin/hass
|
||||
[...]
|
||||
```
|
||||
|
||||
To get Home Assistant's logging output, simple use `journalctl`.
|
||||
|
||||
```bash
|
||||
$ journalctl -f -u home-assistant@[your user]
|
||||
```
|
||||
|
||||
Because the log can scroll quite quickly, you might want to open a second terminal to view only the errors:
|
||||
```bash
|
||||
$ journalctl -f -u home-assistant@[your user] | grep -i 'error'
|
||||
```
|
||||
137
source/_docs/autostart/upstart.markdown
Normal file
137
source/_docs/autostart/upstart.markdown
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Autostart using Upstart"
|
||||
description: "Instructions how to setup Home Assistant to launch on boot using Upstart."
|
||||
date: 2015-9-1 22:57
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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. 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 could look like the sample below.
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
### BEGIN INIT INFO
|
||||
# Provides: hass
|
||||
# Required-Start: $local_fs $network $named $time $syslog
|
||||
# Required-Stop: $local_fs $network $named $time $syslog
|
||||
# Default-Start: 2 3 4 5
|
||||
# Default-Stop: 0 1 6
|
||||
# Description: Home\ Assistant
|
||||
### END INIT INFO
|
||||
|
||||
# /etc/init.d Service Script for Home Assistant
|
||||
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
|
||||
#
|
||||
# Installation:
|
||||
# 1) If any commands need to run before executing hass (like loading a
|
||||
# virutal environment), put them in PRE_EXEC. This command must end with
|
||||
# a semicolon.
|
||||
# 2) Set RUN_AS to the username that should be used to execute hass.
|
||||
# 3) Copy this script to /etc/init.d/
|
||||
# sudo cp hass-daemon /etc/init.d/hass-daemon
|
||||
# sudo chmod +x /etc/init.d/hass-daemon
|
||||
# 4) Register the daemon with Linux
|
||||
# sudo update-rc.d hass-daemon defaults
|
||||
# 5) Install this service
|
||||
# sudo service hass-daemon install
|
||||
# 6) Restart Machine
|
||||
#
|
||||
# After installation, HA should start automatically. If HA does not start,
|
||||
# check the log file output for errors.
|
||||
# /var/opt/homeassistant/home-assistant.log
|
||||
|
||||
PRE_EXEC=""
|
||||
RUN_AS="USER"
|
||||
PID_FILE="/var/run/hass.pid"
|
||||
CONFIG_DIR="/var/opt/homeassistant"
|
||||
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --daemon"
|
||||
REDIRECT="> $CONFIG_DIR/home-assistant.log 2>&1"
|
||||
|
||||
start() {
|
||||
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
|
||||
echo 'Service already running' >&2
|
||||
return 1
|
||||
fi
|
||||
echo 'Starting service…' >&2
|
||||
local CMD="$PRE_EXEC hass $FLAGS $REDIRECT;"
|
||||
su -c "$CMD" $RUN_AS
|
||||
echo 'Service started' >&2
|
||||
}
|
||||
|
||||
stop() {
|
||||
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
|
||||
echo 'Service not running' >&2
|
||||
return 1
|
||||
fi
|
||||
echo 'Stopping service…' >&2
|
||||
kill -3 $(cat "$PID_FILE")
|
||||
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
|
||||
echo 'Service stopped' >&2
|
||||
}
|
||||
|
||||
install() {
|
||||
echo "Installing Home Assistant Daemon (hass-daemon)"
|
||||
echo "999999" > $PID_FILE
|
||||
chown $RUN_AS $PID_FILE
|
||||
mkdir -p $CONFIG_DIR
|
||||
chown $RUN_AS $CONFIG_DIR
|
||||
}
|
||||
|
||||
uninstall() {
|
||||
echo -n "Are you really sure you want to uninstall this service? That cannot be undone. [yes|No] "
|
||||
local SURE
|
||||
read SURE
|
||||
if [ "$SURE" = "yes" ]; then
|
||||
stop
|
||||
rm -fv "$PID_FILE"
|
||||
echo "Notice: The config directory has not been removed"
|
||||
echo $CONFIG_DIR
|
||||
update-rc.d -f hass-daemon remove
|
||||
rm -fv "$0"
|
||||
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
|
||||
fi
|
||||
}
|
||||
|
||||
case "$1" in
|
||||
start)
|
||||
start
|
||||
;;
|
||||
stop)
|
||||
stop
|
||||
;;
|
||||
install)
|
||||
install
|
||||
;;
|
||||
uninstall)
|
||||
uninstall
|
||||
;;
|
||||
restart)
|
||||
stop
|
||||
start
|
||||
;;
|
||||
*)
|
||||
echo "Usage: $0 {start|stop|restart|install|uninstall}"
|
||||
esac
|
||||
```
|
||||
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue