Install Heimdall - TrueNAS CORE jail

heimdall-script.md

Setup Heimdall on TrueNAS Core

Successfully tested on TrueNAS-13.0-U6.1 on 28.03.2024

Prerequisites

1. Open your TrueNAS WebUI and go to Jails
2. Click on ADD and start the creation wizard
3. Wizard Step 1: Name your jal e.g. heimdall and choose release 13.3
4. Wizard Step 2: Check both DHCP Autoconfigure IPv4 and VNET
5. Wizard Step 3: Confirm the setup by clicking SUBMIT
6. After the jail is created, click on chevron on the right side and init a shell session via the button SHELL

Script

pkg update -f && pkg upgrade
# install a favourite editor
pkg install vim
pkg install mcedit
pkg install nano

PHP

pkg install php83 php83-{ctype,curl,dom,fileinfo,filter,mbstring,pdo,session,tokenizer,xml,zip,phar,zlib,intl,simplexml,sodium,xmlwriter,pdo_sqlite}
cp /usr/local/etc/php.ini-production /usr/local/etc/php.ini
mcedit /usr/local/etc/php.ini # the defaults PHP config values should be fine, but you could adjust some of them

PHP FPM

mkdir /usr/local/etc/php-fpm.d

confirm that the PHP-FPM conf file contains an "include" end line last line: include=/usr/local/etc/php-fpm.d/*.conf

vi /usr/local/etc/php-fpm.conf # check last line of file
echo 'php_fpm_enable="YES"' >> /etc/rc.conf
vi /usr/local/etc/php-fpm.d/heimdall.example.com.conf # create the heimdall php-fpm pool config file:

# content of heimdall.example.com.conf

[heimdall.example.com]
user = heimdall
group = www
listen = /var/run/heimdall.example.com-php-fpm.sock
listen.owner = heimdall
listen.group = www
pm = dynamic
pm.max_children = 35
pm.start_servers = 15
pm.min_spare_servers = 15
pm.max_spare_servers = 20

mofify the default php-fpm config file and update the request_terminate_timeout option

make sure the line exists and is not commented request_terminate_timeout = 300

vi  /usr/local/etc/php-fpm.d/www.conf

Setup composer

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f88543c636f7cd84f6db9189d43a81e5503cda447da73c7e5b6') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

Create a user for Heimdall

pw user add -n heimdall -s /sbin/nologin -c "Heimdall"

Setup Heimdall

cd /usr/local/www
git clone https://github.com/linuxserver/Heimdall.git
cd Heimdall
../composer.phar i
php artisan key:generate
chown -R heimdall:www /usr/local/www/Heimdall # set the right owner

Setup nginx

pkg install nginx
echo 'nginx_enable="YES"' >> /etc/rc.conf
service nginx start
mkdir /usr/local/etc/nginx/conf.d
echo '' > /usr/local/etc/nginx/nginx.conf

edit the default config file and replace its content:

vim /usr/local/etc/nginx/nginx.conf

# content of nginx.conf

load_module /usr/local/libexec/nginx/ngx_mail_module.so;
load_module /usr/local/libexec/nginx/ngx_stream_module.so;

worker_processes  1;
error_log  /var/log/nginx-error.log;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    # Load config files from the /etc/nginx/conf.d directory
    include /usr/local/etc/nginx/conf.d/*.conf;
}

create config file for heimdall

vi /usr/local/etc/nginx/conf.d/heimdall.example.com.conf

don't forget to replace <<<YOUR_DOMAIN>>> with your domain and <<<PATH_TO_PUBLIC_CERT_FILE>>> and <<<PATH_TO_PRIVATE_KEY_FILE>>> with the path to your SSL certificate and key

# content of heimdall.example.com.conf

upstream heimdall-handler {
    server unix:/var/run/heimdall.example.com-php-fpm.sock;
}

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;
}

server {
    server_name www.<<<YOUR_DOMAIN>>>;
    return 301 $scheme://<<<YOUR_DOMAIN>>>$request_uri;
}

server {
    listen 443 ssl http2 default_server;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers TLS-CHACHA20-POLY1305-SHA256:TLS-AES-256-GCM-SHA384:TLS-AES-128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

    server_name <<<YOUR_DOMAIN>>>;

    access_log /var/log/nginx/access.log;
    error_log  /var/log/nginx/error.log info;
    
    ssl_certificate     <<<PATH_TO_PUBLIC_CERT_FILE>>>;
    ssl_certificate_key <<<PATH_TO_PRIVATE_KEY_FILE>>>;
    ssl_session_timeout 1d;

    add_header Strict-Transport-Security "max-age=7200";

    root /usr/local/www/Heimdall/public;
    index index.php;
  
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
  
    location ~ \.php(?:$|/) {
              fastcgi_split_path_info ^(.+\.php)(/.+)$;
              fastcgi_index index.php;
              include fastcgi_params;
              fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
              fastcgi_param PATH_INFO $fastcgi_path_info;
              fastcgi_pass heimdall-handler;
              fastcgi_intercept_errors on;
              proxy_connect_timeout 600s;
              proxy_send_timeout 600s;
              proxy_read_timeout 600s;
              fastcgi_send_timeout 600s;
              fastcgi_read_timeout 600s;
    }
}

Note: The code above assumes you have SSL certificates

Final restarts

service nginx restart
service php-fpm start

Conclusion

You should have a running Heimdall dashboard that's served by nginx.

Last thing I did is have my router forward request on port 443 to the jail IP that DHCP gave me.

If that is not working for you then I suggest you go back to the Heimdall directory and start the Laravel server manually.

cd /usr/local/www/Heimdall
php artisan serve --host <<<YOUR JAIL'S IP>>>

I would imagine that Heimdall is now accessible at the IP you provided to the serve command.

Disclaimer

I am an enthusiast that is curious about configuring their own home server. Aware of my limited knowledge I welcome any feedback so that we make this script better.

That said, I hope my struggles can help others!

Wishing you luck!

Emil