Update Freenas docs (#11585)

* updated rc.d script

Add extra_commands

	check_config - checks config using `hass --script check_config`
	upgrade - stops HA / upgrade / checks config / starts HA (only starts if config check passes)
	test - simple test to check directories / activate venv / check version of python and homeassistant
	restart - (modified) check_config / stop HA /start HA (only restart if config check passes)

NOTE: All extra_commands REQUIRE bash to be installed
	`pkg install bash`

I also removed the check_config from the pre_start function because because it will prevent HA from starting
if the configuration is missing (Like a clean install from example). NO BUENO!

Another case to consider haveing no configuration even after initial install is troubleshooting or testing.
For instance with rc.d script createing a fresh config is simple.

Let's suppose my working config is at
	`/home/hass/homeassistant`

Now to get a clean configuration I can just do this
	service homeassistant stop
	sysrc sysrc homeassistant_config_dir="/home/hass/ha_test_config"
	service homeassistant start

That's it! Configuration wise, it's a clean install. To switch back to working config I just
	service homeassistant stop
        sysrc sysrc homeassistant_config_dir="/home/hass/homeassistant"
        service homeassistant start

Awesome right?! But that doesn't work if check_config fails during pre_start

* add pkgs

These are not required to install HA but they are quickly missed once you start to actual use it. Let's just avoid
some fustration from the start. I don't think this list should be all inclusive but these basic things seem to be
frequently needed from the start.

	autoconf |
	gmake    | - looking at you Z-Wave, Stream, IKEA Tradfri
	pkgconf  |

	bash - Give me bash or give me death! Seriously, it makes life easier. There's not alot of *BSD focus
		around HA. I only use *BSD because of FreeNAS -- Typically (with the exception of jails) FreeNAS is webui.
		I'm ok with Linux cli and it's very similiar to FreeNAS but not the same. It's not bash. I don't think it
		needs to be for the root user either. But having bash installed and used by the HA user makes it easier
		to follow along with exising documentation for other virtualenv type installs when trying to further expand
		your HA installation

* give me bash or give me death!

Most people won't notice a differene but we'll know in our hearts we did the right thing.

* fix typo

I'm lucky I can spell my name

* whitespace

* use venv

Use the built-in venv instead of virtualenv which must be installed seperate.
This commit is contained in:
Troy Prelog 2020-01-05 04:29:16 -05:00 committed by Franck Nijhof
parent 2675661e67
commit a4e6ff1e7a

View File

@ -13,22 +13,19 @@ Enter the Home Assistant jail. If you don't know which name you have given the j
iocage exec HomeAssistant
```
Create the user and group that Home Assistant will run as. The user/group ID of `8123` can be replaced if this is already in use in your environment.
```bash
pw groupadd -n homeassistant -g 8123
echo 'homeassistant:8123:8123::::::/bin/csh:' | adduser -f -
```
Install the necessary Python packages and virtualenv:
Install the suggested packages:
```bash
pkg update
pkg upgrade
pkg install -y python37 py37-sqlite3 ca_root_nss
python3.7 -m ensurepip
pip3 install --upgrade pip
pip3 install --upgrade virtualenv
pkg install -y autoconf bash ca_root_nss gmake pkgconf python37 py37-sqlite3
```
Create the user and group that Home Assistant will run as. The user/group ID of `8123` can be replaced if this is already in use in your environment.
```bash
pw groupadd -n homeassistant -g 8123
echo 'homeassistant:8123:8123::::::/usr/local/bin/bash:' | adduser -f -
```
Create the installation directory:
@ -38,13 +35,14 @@ mkdir -p /usr/local/share/homeassistant
chown -R homeassistant:homeassistant /usr/local/share/homeassistant
```
Install Home Assistant itself:
Create the virtualenv and install Home Assistant itself:
```bash
su homeassistant
cd /usr/local/share/homeassistant
virtualenv -p python3.7 .
source ./bin/activate.csh
python3.7 -m venv .
source ./bin/activate
pip3 install --upgrade pip
pip3 install homeassistant
```
@ -82,29 +80,37 @@ vi /usr/local/etc/rc.d/homeassistant
```bash
#!/bin/sh
#
# Based upon work by tprelog at https://www.ixsystems.com/community/resources/fn-11-2-iocage-home-assistant-jail-plugins-for-node-red-mosquitto-amazon-dash-tasmoadmin.102/
# Based upon work by tprelog at https://github.com/tprelog/iocage-homeassistant/blob/11.3-RELEASE/overlay/usr/local/etc/rc.d/homeassistant
#
# PROVIDE: homeassistant
# REQUIRE: LOGIN
# KEYWORD: shutdown
#
# homeassistant_enable: Set to YES to enable the homeassistant service.
# Default: NO
# homeassistant_user: The user account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run as root.
# Default: homeassistant
# homeassistant_group: The group account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run with group wheel.
# Default: homeassistant
# homeassistant_config_dir: Directory where config files are located.
# Default: /home/homeassistant/.homeassistant
# homeassistant_install_dir: Directory where Home Assistant is installed.
# Default: /usr/local/share/homeassistant
# homeassistant_user: The user account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run as root.
# Default: homeassistant
# homeassistant_group: The group account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run with group wheel.
# Default: homeassistant
#
# sysrc homeassistant_enable=yes
# service homeassistant start
# homeassistant_venv: Directory where homeassistant virtualenv is installed.
# Default: "/usr/local/share/homeassistant"
# Change: `sysrc homeassistant_venv="/srv/homeassistant"`
# UnChange: `sysrc -x homeassistant_venv`
#
# homeassistant_config_dir: Directory where homeassistant config is located.
# Default: "/home/homeassistant/.homeassistant"
# Change: `sysrc homeassistant_config_dir="/home/hass/homeassistant"`
# UnChange: `sysrc -x homeassistant_config_dir`
# -------------------------------------------------------
# Copy this file to '/usr/local/etc/rc.d/homeassistant'
# `chmod +x /usr/local/etc/rc.d/homeassistant`
# `sysrc homeassistant_enable=yes`
# `service homeassistant start`
# -------------------------------------------------------
. /etc/rc.subr
name=homeassistant
@ -118,37 +124,78 @@ load_rc_config ${name}
: ${homeassistant_user:="homeassistant"}
: ${homeassistant_group:="homeassistant"}
: ${homeassistant_config_dir:="/home/homeassistant/.homeassistant"}
: ${homeassistant_install_dir:="/usr/local/share/homeassistant"}
: ${homeassistant_venv:="/usr/local/share/homeassistant"}
command="/usr/sbin/daemon"
extra_commands="check_config restart test upgrade"
start_precmd=${name}_precmd
homeassistant_precmd()
{
rc_flags="-f -P ${pidfile} -p ${pidfile_child} ${homeassistant_install_dir}/bin/hass --config ${homeassistant_config_dir} ${rc_flags}"
if [ ! -e "${pidfile_child}" ]; then
install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile_child}";
fi
if [ ! -e "${pidfile}" ]; then
install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile}";
fi
homeassistant_precmd() {
rc_flags="-f -o ${logfile} -P ${pidfile} -p ${pidfile_child} ${homeassistant_venv}/bin/hass --config ${homeassistant_config_dir} ${rc_flags}"
[ ! -e "${pidfile_child}" ] && install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile_child}"
[ ! -e "${pidfile}" ] && install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile}"
[ -e "${logfile}" ] && rm -f -- "${logfile}"
install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${logfile}"
if [ ! -d "${homeassistant_config_dir}" ]; then
install -d -g ${homeassistant_group} -o ${homeassistant_user} -- "${homeassistant_config_dir}";
install -d -g ${homeassistant_group} -o ${homeassistant_user} -m 775 -- "${homeassistant_config_dir}"
fi
echo "Performing check on Home Assistant configuration:"
eval "${homeassistant_install_dir}/bin/hass" --config "${homeassistant_config_dir}" --script check_config
}
stop_postcmd=${name}_postcmd
homeassistant_postcmd()
{
homeassistant_postcmd() {
rm -f -- "${pidfile}"
rm -f -- "${pidfile_child}"
}
upgrade_cmd="${name}_upgrade"
homeassistant_upgrade() {
service ${name} stop
su ${homeassistant_user} -c '
source ${@}/bin/activate || exit 1
pip3 install --upgrade homeassistant
deactivate
' _ ${homeassistant_venv} || exit 1
[ $? == 0 ] && homeassistant_check_config && service ${name} start
}
check_config_cmd="${name}_check_config"
homeassistant_check_config() {
[ ! -e "${homeassistant_config_dir}/configuration.yaml" ] && return 0
echo "Performing check on Home Assistant configuration:"
#eval "${homeassistant_venv}/bin/hass --config ${homeassistant_config_dir} --script check_config"
su ${homeassistant_user} -c '
source ${1}/bin/activate || exit 2
hass --config ${2} --script check_config || exit 3
deactivate
' _ ${homeassistant_venv} ${homeassistant_config_dir}
}
restart_cmd="${name}_restart"
homeassistant_restart() {
homeassistant_check_config || exit 1
echo "Restarting Home Assistant"
service ${name} stop
service ${name} start
}
test_cmd="${name}_test"
homeassistant_test() {
echo -e "\nTesting virtualenv...\n"
[ ! -d "${homeassistant_venv}" ] && echo -e " NO DIRECTORY: ${homeassistant_venv}\n" && exit
[ ! -f "${homeassistant_venv}/bin/activate" ] && echo -e " NO FILE: ${homeassistant_venv}/bin/activate\n" && exit
## switch users / activate virtualenv / get version
su "${homeassistant_user}" -c '
source ${1}/bin/activate || exit 2
echo " $(python --version)" || exit 3
echo " Home Assistant $(pip3 show homeassistant | grep Version | cut -d" " -f2)" || exit 4
deactivate
' _ ${homeassistant_venv}
[ $? != 0 ] && echo "exit $?"
}
load_rc_config ${name}
run_rc_command "$1"
```
@ -204,8 +251,8 @@ vi /etc/devfs.rules
Add the following lines
```bash
[devfsrules_jail_allow_usb=7]
add path 'cu\*' mode 0660 group 8123 unhide
[devfsrules_jail_allow_usb=7]
add path 'cu\*' mode 0660 group 8123 unhide
```
Reload devfs
@ -261,7 +308,7 @@ Then, enter the `venv`:
```bash
su homeassistant
cd /usr/local/share/homeassistant
source ./bin/activate.csh
source ./bin/activate
```
Upgrade Home Assistant: