truenas-iocage-homeassistant

Script to create an iocage jail on TrueNAS with homeassistant and caddy.

This is an unsupported installation of Home Assistant Core. It works, but be advised.

This script will create an iocage jail on TrueNAS CORE 13.0 with the latest release of homeassistant. It will obtain a trusted certificate from Let's Encrypt for the system, install it, and configure it to renew automatically. It will configure the jail to store the data outside the jail, so it will not be lost in the event you need to rebuild the jail.

Status

This script will work with TrueNAS CORE 13.0. Due to the EOL status of FreeBSD 12.0, it is unlikely to work reliably with earlier releases of FreeNAS.

Usage

Prerequisites (Let's Encrypt)

This script works best when your installation is able to obtain a certificate from Let's Encrypt. When you use it this way, Caddy is able to handle all of the TLS-related configuration for you, obtain and renew certificates automatically, etc. In order for this to happen, you must meet the two requirements below:

First, you must own or control a real Internet domain name. This script obtains a TLS encryption certificate from Let's Encrypt, who will only issue for public domain names. Thus, domains like homeassistant.local, myhome.lan, or assistant.home won't work. Domains can be very inexpensive, and in some cases, they can be free. Freenom, for example, provides domains for free if you jump through the right hoops. EasyDNS is a fine domain registrar for paid domains, costing roughly US$15 per year (which varies slightly with the top-level domain).
Second, one of these two conditions must be met in order for Let's Encrypt to validate your control over the domain name:
- You must be able and willing to open ports 80 and 443 from the entire Internet to the jail, and leave them open. If this applies, do it before running this script.
- DNS hosting for the domain name needs to be with a provider that Caddy supports. At this time, only Cloudflare is supported as it is the only one I have tested with this script.

Cloudflare provides DNS hosting at no cost, and it's well-supported by Caddy. Cloudflare also provides Dynamic DNS service, if your desired Dynamic DNS client supports their API.

Cloudflare has removed the ability to use its API with free domains when using Cloudflare's free plan. For this to work, you'll need to pay either for Cloudflare or for a domain (and the latter is likely less expensive). If you want to use a Freenom domain, you'll need to be able and willing to open ports 80 and 443 to your jail, so you can get your certificate without using DNS validation.

If you aren't able or willing to obtain a certificate from Let's Encrypt, this script also supports configuring Caddy with a self-signed certificate, or with no certificate (and thus no HTTPS) at all.

Prerequisites

You will need to create

1 Dataset named homeassistant in your pool. e.g. /mnt/mypool/homeassistant

If this is not present, a directory /homeassistant will be created in $POOL_PATH. You will want to create the dataset, otherwise a directory will just be created. Datasets make it easy to do snapshots etc...

Installation

Download the repository to a convenient directory on your TrueNAS system by changing to that directory and running git clone https://github.com/tschettervictor/truenas-iocage-homeassistant. Then change into the new truenas-iocage-homeassistant directory and create a file called homeassistant-config with your favorite text editor. In its minimal form, it would look like this:

JAIL_IP="192.168.1.199"
DEFAULT_GW_IP="192.168.1.1"
POOL_PATH="/mnt/mypool"
HOST_NAME="YOUR_FQDN"
SELFSIGNED_CERT=1

Many of the options are self-explanatory, and all should be adjusted to suit your needs, but only a few are mandatory. The mandatory options are:

JAIL_IP is the IP address for your jail. You can optionally add the netmask in CIDR notation (e.g., 192.168.1.199/24). If not specified, the netmask defaults to 24 bits. Values of less than 8 bits or more than 30 bits are invalid.
DEFAULT_GW_IP is the address for your default gateway
POOL_PATH is the path for your data pool.
HOST_NAME is the fully-qualified domain name you want to assign to your installation. If you are planning to get a Let's Encrypt certificate (recommended), you must own (or at least control) this domain, because Let's Encrypt will test that control. If you're using a self-signed cert, or not getting a cert at all, it's only important that this hostname resolve to your jail inside your network.
DNS_CERT, STANDALONE_CERT, SELFSIGNED_CERT, and NO_CERT determine which method will be used to generate a TLS certificate (or, in the case of NO_CERT, indicate that you don't want to use SSL at all). DNS_CERT and STANDALONE_CERT indicate use of DNS or HTTP validation for Let's Encrypt, respectively. One and only one of these must be set to 1.
DNS_PLUGIN: If DNS_CERT is set, DNS_PLUGIN must contain the name of the DNS validation plugin you'll use with Caddy to validate domain control. At this time, the only valid value is cloudflare (but see below).
DNS_TOKEN: If DNS_CERT is set, this must be set to a properly-scoped Cloudflare API Token. You will need to create an API token through Cloudflare's dashboard, which must have "Zone / Zone / Read" and "Zone / DNS / Edit" permissions on the zone (i.e., the domain) you're using for your installation. See this documentation for further details.
CERT_EMAIL: If you're obtaining a cert from Let's Encrypt (i.e., either DNS_CERT or STANDALONE_CERT is set to 1), this must be set to a valid email address. You'll only receive mail there if your cert is about to expire (which should never happen), or if there are significant announcements from Let's Encrypt (which is unlikely to result in more than a few emails per year).

In addition, there are some other options which have sensible defaults, but can be adjusted if needed. These are:

JAIL_NAME: The name of the jail, defaults to "homeassistant"
INTERFACE: The network interface to use for the jail. Defaults to vnet0.
JAIL_INTERFACES: Defaults to vnet0:bridge0, but you can use this option to select a different network bridge if desired. This is an advanced option; you're on your own here.
VNET: Whether to use the iocage virtual network stack. Defaults to on.

If you're going to open ports 80 and 443 from the outside world to your jail, do so before running the script, and set STANDALONE_CERT to 1. If not, but you use a DNS provider that's supported by Caddy, set DNS_CERT to 1. If neither of these is true, use either NO_CERT (if you want to run without SSL at all) or SELFSIGNED_CERT (to generate a self-signed certificate--this is also the setting to use if you want to use a certificate from another source).

Also, HOST_NAME needs to resolve to your jail from inside your network. You'll probably need to configure this on your router, or on whatever other device provides DNS for your LAN. If you're unable to do so, you can edit the hosts file on your client computers to achieve this result, but consider installing something like Pi-Hole to give you control over your DNS.

Obtaining a trusted Let's Encrypt cert

This configuration generated by this script will obtain certs from a non-trusted certificate authority by default. This is to prevent you from exhausting the Let's Encrypt rate limits while you're testing things out. Once you're sure things are working, you'll want to get a trusted cert instead. To do this, you can use a simple script that's included. As long as you haven't changed the default jail name, you can do this by running iocage exec homeassistant /root/remove-staging.sh (if you have changed the jail name, replace "homeassistant" in that command with the jail name).

DNS Providers

This script has only been tested with Cloudflare, which works well.

Visit the Caddy download page to see the DNS authentication plugins currently available. To build Caddy with your desired plugin, use the last part of the "Package" on that page as DNS_PLUGIN in your homeassistant-config file. E.g., if the package name is github.com/caddy-dns/cloudflare, you'd set DNS_PLUGIN=cloudflare. From that page, there are also links to the documentation for each plugin, which will describe what credentials are needed. If your provider needs only an API token (as is the case with Cloudflare, and apparently with DNSPod and Gandi), you'll likely be able to set DNS_TOKEN=long_api_token in the homeassistant-config file and not need to do anything else. If your provider requires different credentials, you'll need to modify the Caddyfile to account for them.

Execution

Once you've downloaded the script and prepared the configuration file, run this script (script homeassistant.log ./homeassistant-jail.sh). You will be prompted to copy a default configuration.yaml file, or to not copy it at the end of the script. It is a modified version of the standard one with a few exceptions.

It is configured to allow caddy to reverse proxy.
It has all the default integrations except "bluetooth" and "stream" because these cause errors on FreeBSD. By default the configuration.yaml file will be copied automatically if you dont choose "n" at the prompt. Only choose "n" if it is a reinstall, or you have your own file configured.

Once the script is finished, you will need to wait 5-10 minutes for setup to complete within homeassistant itself.

Notes

This script uses the same RC Service Script from @tprelog on the TrueNAS forums. Credits go to him for that.
This is an unsupported installation of Homeassistant Core, but it works fairly well as of right now.
It is basically the same thing as the plugin that used to exist on TrueNAS community plugins.
The configuration.yaml file is located at /home/homeassistant/config
The Caddyfile is located at /usr/local/www/Caddyfile

tschettervictor / truenas-iocage-homeassistant Goto Github PK