Install Heimdall Dashboard in a jail (script) - FreeNAS 11.2

Introduction

Heimdall Dashboard is a web application that acts as a dashboard for other web applications. You can use it as a browser home page if desired, or just set a bookmark there to get to your other applications (like, for example, Plex, Sonarr, Radarr, and even FreeNAS itself). Once you’ve added a few applications and set a background image, it looks something like this:

Installation

To install on your FreeNAS server, first set a pool as active for jails in the web GUI under Jails -> Config. Change to a convenient directory on your server, and clone the git repository using git clone https://github.com/danb35/freenas-iocage-heimdall. Change into the freenas-iocage-heimdall directory, and edit the script. Set the configuration options at the beginning (shown below) as appropriate. FILE needs to be set to the file name of the latest release–at this writing, the latest release is 2.2.2, so FILE is set to 2.2.2.tar.gz.

# Set these variables as appropriate
# FILE should be set to the version number of the latest release, with .tar.gz added
JAIL_NAME="heimdall"
JAIL_IP=192.168.1.204
DEFAULT_GW_IP=192.168.1.1
CERT_EMAIL="nobody@example.com"
FILE="2.2.2.tar.gz"

Then run the script (./heimdall-jail.sh). When it’s complete, browse to http://JAIL_IP to see your Heimdall home page. It should look like this:

If you don’t want to configure TLS access for Heimdall, you’re done. If you do, read on.

TLS Configuration (Optional)

If you’d like to set up this jail to use TLS with a trusted certificate from Let’s Encrypt, you’ll need to make a few changes. I’m assuming here that you own your own domain, and that you don’t want to forward port 443 from the Internet to your jail (which you shouldn’t want to do). As a result, you’ll need to host your DNS with a service that’s supported by Caddy; see the list of compatible providers under the heading of DNS Providers at the Caddy documentation. Cloudflare works well and provides DNS service at no cost, and I’ll use that in the remaining instructions.

For this to work without giving you certificate errors, you’ll need to assign a hostname to your jail, and have that hostname resolve to the jail. I do this by setting a DNS entry in my pfSense router pointing heimdall.mydomain.com to the jail; if your router doesn’t support this feature, you can achieve the same result by editing /etc/hosts (on a Unix-y computer) or HOSTS.TXT (on a Windows computer).

Enter your jail using iocage console heimdall. Lock the Caddy package (to keep package updates from overwriting the custom version we’re about to install) using pkg lock caddy. You’ll also need to install a couple of other packages; run pkg install curl bash to do this.

Then visit the Caddy download page, set the platform to FreeBSD 64-bit, and then click on Add plugins. Check the box for your DNS provider (for Cloudflare, it would be tls.dns.cloudflare). Then click Choose under the “Plan” heading and, assuming you’ll be using this jail entirely for personal use, select Personal. Then scroll down on that page and copy the line for the “one-step installer script” (if using Cloudflare, it will be curl https://getcaddy.com | bash -s personal tls.dns.cloudflare). Run that command in the jail.

You’ll then need to set two configuration variables. Run sysrc caddy_cert_email=you@yourdomain.com–this email address will be used by Let’s Encrypt to notify you of certificate expiration (which shouldn’t happen under normal circumstances) and other important issues. Then run sysrc caddy_env="CLOUDFLARE_EMAIL=(cloudflare_account_email) CLOUDFLARE_API_KEY=(global_api_key)" Replace (cloudflare_account_email) with the email address on your Cloudflare account, and (global_api_key) with your Cloudflare global API key–you can find this in your account settings. If you’re using a different DNS provider, you’ll need to set caddy_env differently; consult the Caddy docs at the link above to see what credentials your provider needs.

Next, you’ll need to edit the Caddyfile: nano /usr/local/www/Caddyfile. Replace the first line (which should read *:80 {) with the following:

heimdall.yourdomain.com {
tls {
    dns cloudflare
}

Again, replace cloudflare with your DNS provider.

Your configuration is finished; now you only need to restart Caddy: service caddy restart. Then browse to the jail at https://heimdall.yourdomain.com and go from there.