TrueNAS Scale Nextcloud w/ Traefik reverse proxy (https)

TrueNAS Scale Nextcloud w/ Traefik reverse proxy (https)

Recently I’ve migrated from TrueNAS Core (formerly known as FreeNAS, FreeBSD-based) to TrueNAS Scale (Debian-based). Thus, I had to move web apps like Nextcloud, Plex, etc. from FreeBSD Jails to Kubernetes Pods manually. I would like to briefly introduce these different two virtualization techniques here below.

FreeBSD Jail

First things first — what is FreeBSD? FreeBSD is an operating system which has a bunch of advanced features. One such feature is soft update for the UFS filesystem. Another such feature is called Jail, which is the front runner to the containers we use today. A Jail enables process and its children processes to run in a sandbox, i.e., they have separate file system, hostname, IP address, etc. In other words, jailed process cannot interact with processes in another jail, and each jail has its own superuser.

So… how did they implement Jail? They patched FreeBSD kernel to be aware of if it is inside jail. For example, there is a statement if(superuser) then do (something). After being modified, it should be if(superuser and in jail) then do (something) or more typically if(superuser and not in jail) then do (something).

Example FreeBSD kernel code for getting aware of jail.

The features of FreeBSD Jail make it a great candidate for hosting web applications. For example, we have a WordPress service running in one jail with its IP 192.168.0.100, and a Plex service running in another jail with IP 192.168.0.101. They cannot interact with each other and if one crashes, the other service is unaffected.

You would say we can run the applications in virtual machines (bhyve in FreeBSD) but don’t forget such VMs have its own OS layer and take much more resources.

Kubernetes (K8s)

Actually, Kubernetes is not a type of virtualization method, it is a container manager. Wait, what is container? It is more or less like FreeBSD Jail which runs a group of processes in an isolated environment by leveraging kernel features. The most popular one is Docker container. With kernel namespaces, every container has its own file system, users and network stack, and resources can be limited by cgroups (which FreeBSD Jail cannot provide with). We create Pods (a group of one or more containers) via Kubernetes just like we create FreeBSD Jail via iocage. For example, a WordPress pod may have three containers: one for apache web server, another for sql database, and the other for redis. Kubernetes provides some advanced features like scaling and load balancing, but here in TrueNAS Scale we just use its basic functions.

0. Prerequisites

In order to host Nextcloud with your custom domain name, you must have:

  1. TrueNAS Scale
  2. Domain
  3. Cloudflare account
  4. Public IP
  5. Router with port forwarding and NAT hairpin enabled

1. Setup App environment

If you haven’t setup any app before, you are required to assign a pool for storing app. It might take a while to fetch app catalogs from the Internet.

Assign a pool for apps. Here I use pool “TANK” for example.

Although there is an official nextcloud app in available applications tab, we don’t use this one. Instead, to use reverse proxy and integrate with ingress, we have to add TrueCharts catalog manually and use its nextcloud. Head to “manage catalogs” tab, and click “add catalog” button above.

Catalog name can be just truecharts; repository is https://github.com/truecharts/catalog; preferred trains are stable and core; branch remains main. Click save to proceed. Again, it takes a while to fetch and validate catalog. You can click task manager (at upper-right corner) to view tasks in progress.

After all the tasks are finished, head to “available applications”, you should see a bunch of TrueCharts apps. If not, click “refresh all” button above.

If you are running TrueNAS SCALE 22.02-RC.2, there is an existing issue which causes web interface very slow. There is a patch to resolve this (this is only for RC.2 release, and is not required for SCALE 22.02.0 and future releases):

curl -s https://truecharts.org/rc2patcher | bash
Select “system settings” in the left menu, and click “shell”.
Type-in patch command and click enter. Web interface will restart after being patched.

2. Install and configure Traefik reverse proxy

Traefik is a reverse proxy (actually much more than that, but we will just use this function in TrueNAS) service which routes network traffic from different hostnames to belonged apps. To install this, just head to “available applications” tab and search for traefik. Click install to proceed.

Just give this app a name and click next.

After giving this app a name (e.g., traefik), you can just click “next” buttons until step 5 “Nextworking and Services”. Here you will see three numbers: 9000, 9080, and 9443. So, 9000 the port number for Traefik its own web interface (to monitor route setting for example); 9080 is the unsecured (http://) entry point port; 9443 is secured (https://) port. If you want to redirect http to https for your apps, click “show advanced settings” right below 9080, and put 443 in “redirect to port” text field. Note that “redirect to entrypoint” should be empty.

Click “next” to the end, and save the setting to install it!

Should see traefik in “installed applications’ tab.
Click “web portal” button, and you will see Traefik dashboard web interface.

3. Setup ACME certificates with Cloudflare account

So far TrueNAS only supports Cloudflare and route53 to verify ACME DNS challenges automatically. Here we will go with Cloudflare.

3.1. Fetch Cloudflare API

Let’s suppose you are using Cloudflare to manage your domain name. If not, just migrate to it! We will need Global API Key, which can be viewed in settings -> API Tokens tab.

3.2. Setup ACME DNS challenges

You are required to have email address for root before proceeding.

Head to “credentials” menu and select “local users” tab. Click user “root” to edit.
Give it an email address.

All certificates have expired dates. We will setup auto renewal for certificates through DNS challenges. Head to “credentials” menu and select “certificates” tab, click “add” in “ACME DNS-Authenticators” block.

Just give it a name (e.g., your domain), select “cloudflare” in authenticator, and type-in your registered email and global API key.

Now we need to create CSR as well: click add in that block. Give it a name again and click next.

In step 3 “Certificate Subject”, be sure to put your domain name in “common name” text field, and all of domains you will use in “subject alternate names” field. Here you can use wildcard like *.windsketch.cc which matches all sub-domains. Click next to save it.

After successfully creating CSR, click the wrench icon 🔧 to create ACME certificate. Give it a name like ACME_CERT and make sure to choose “Let’s Encrypt Production Directory” in ACME Server Directory URI (otherwise certificates will be in testing mode). Select our newly created DNS authenticator below.

If you see a certificate entry shown in “certificates” block with valid expired date, you are all set!

4. Install Nextcloud

In this section, we will install TrueCharts-based nextcloud. Click “refresh all” again to let ingress know you’ve added new certificate. Search application “nextcloud”, and there are two apps. Just choose “TrueCharts” one and click install.

Choose right one to install.

If you want to migrate from existing Nextcloud, you are required to setup mount points (for example, /var/www/html/config is the path for config folder inside the container for TrueCharts-based Nextcloud) and set owner and group to www-data:www-data for existing files. If you are not sure how to do this, feel free to leave a comment!

Put your nextcloud admin username and password here.

In step 6 “Ingress”, click “enable ingress”, add one host with the hostname you would like to use for nextcloud (e.g., nextcloud.windsketch.cc). Path should be / with prefix path type.

For TLS setting, put the same information again, in the dropdown list “Select TrueNAS SCALE Certificate“, be sure to select the certificate we created in the previous section.

Other settings remain defaults. Click “save” to deploy it (it will take longer than Traefik since there are three containers in this pod). If all the settings are set correctly, there will be one entry added automatically in Traefik http routes tab:

By the way, you can use above steps to install any TrueCharts app with your custom domain name! There is also an app called “external-service” which enables unsupported pods (like something you cannot find in TrueCharts catalog and have to manually create) to integrate with Ingress. Let’s say we have a ZoneMinder with address http://192.168.88.73:19080, in the setting it will be:

Example of external-service setup. Don’t forget to enable Ingress and repeat steps above.

5. Setup DNS and port forwarding

Finally, you should add an “A” type DNS record in Cloudflare to point your domain name to the external IP address of TrueNAS, and add port forwarding entries in your router:

Let’s say if you browse http://your.domain.name/, the IP will be resolved via Cloudflare DNS entry and then will try to establish connection to your router (for example, your public IP is 1.2.3.4 and TrueNAS IP is 192.168.88.72), 1.2.3.4:80 (port 80). By port forwarding rules from your router, it will redirect to 192.168.88.72:9080. Next, with the Traefik “redirect to port” setup, port 9080 will redirect to port 443, so it is 1.2.3.4:443 now. Similarly, router redirects 1.2.3.4:443 to 192.168.88.72:9443. Now Traefik will check the domain name and redirect to specific services (for example, redirection to Nextcloud is 192.168.88.72:10020).

Note that you have to enable NAT hairpin (NAT loopback) in your router. Without that, you cannot connect to Nextcloud (or other apps) with domain name (still can browse it directly with IP and port).

If you want proxy enabled for Cloudflare DNS entry, you have to set SSL/TLS encryption mode to “full” to avoid ERR_TOO_MANY_REDIRECTS error.

From now on, access your Nextcloud via https://your.domain.name/ and enjoy 😀!


Update: If you tried to upgrade NextCloud and found that it won’t start anymore, make sure in settings tab of NextCloud app, “Networking and Services” → “Show Advanced settings” → “Target Port” is 8080 (instead of 80). They changed the listening port without updating it while upgrading.

20 thoughts on “TrueNAS Scale Nextcloud w/ Traefik reverse proxy (https)

  1. Hi I am not able to make this working. Could you please help me?
    Do I have to configure the nextcloud config file somehow?

    Best
    Dejan

    1. Hi, what errors or blockers were you facing? Normally default nextcloud config.php should be fine. If you have trusted domain issues, then you might configure config.php or re-create the pod.

  2. Maybe a stupid question, but every app uses their own port. My Nextcloud set itself as 10020, my Jellyfin 8096. Buuut, websecure in Traefik is forcing everything onto subdomain.domain.eu:9443?? Can you please show your Nextcloud container Networking and Services section>

    1. Hi there! I forgot to mention in the post but I am using different subdomain for each service (e.g., nextcloud.domain.eu, jellyfin.domain.eu, etc.) in the step 6 Ingress while creating apps, so that Traefik can forward incoming request to specific port and app based on the url. You can use ‘CNAME’ type DNS record to point them to a single ‘A’ record. In addition, if you’re using wildcard (e.g., *.domain.eu) while creating certificate, it’s good to go and there’s no need to create multiple certificates for every subdomain. Hope this helps to your question.

  3. Hi, i have followed you completely until step 5, everything worked so far as intended. Unfortunately, i am not able to access my nextcloud instance via the defined subdomain.domain… Could you help me detailing part 5 of the guide a bit more? What do you mean by i should put an “A” type entry in cloudflare? My domain is set as a

    1. Sure thing! For adding type A entry, it means create a DNS record to point your defined subdomain.domain… to the IP address you’re hosting nextcloud. You can add one in “DNS” tab by clicking “add record”. If it is setup correctly, you can see your IP address by pinging your domain.

  4. Followed your instruction pretty well, Traefik shows the same but I don’t get next cloud (next cloud words well locally). Don’t know where it went wrong. I do have a Cloudshare but I have turned off the proxie

    1. Hi, if you already have CloudFlare account and valid domain, can you verify the IP is correct from pinging your domain (without proxy)? If DNS is working correctly, then something you should probably look at is port forwarding.

  5. Pinging goes fine, and I have plex and another site (home automation) running from the site. I did everyting as stated and I recevive a copy of truenas from nextcloud.my.website. I dont know what is wrong, I have setup config files in docker before ….. I setup all the needed port forwards,

  6. I did ping my website and it went fine. I also have plex running and through another compter my home automation. When I enter nextcloud.my.website I get a the inlog screen of TrueNAS (also from outside my network). I have setup nextcloud many times (through config.php), but this is something different, I have no clue what traefik does, only my screen is identical to yours.

    1. Hi sorry it seems that some replies went to spam automatically. If you get login screen of TrueNAS when you go to https://nextcloud.my.web then I think you put port forward from 443 to 443 (or 80 to 80) for the TrueNAS local IP, which is not intended to be. Do you have discord account? My ID is windsketch#3025 and if you would like to we can have a quick talk on discord.

  7. Any chance of you doing a example of the non truecharts version of nextcloud aio? I want to set that version up as it is much more complete than the truecharts version. I am figuring it could work with the docker compose truecharts app then the external services app to give it ssl. That would be awesome as Truecharts will not support the AIO edition. Thank you

    1. Yes I can do that later. There’s a “custom-app” made by TrueCharts which integrates Ingress with it so that we no longer need external-service app. Once I figure it out I will let you know!

  8. Hi,

    I am also running in similar issues as above.
    I’ve got an domain name at Cloudflare, made a A record for “mydomain.com” to my ip address at home, and a CNAME record “nextcloud.mydomain.com”

    I setup everything as above in you write-up, including the port forwarding 443->9443 and 80->9080
    In my edgemax router i also see Packets and Bytes coming by for these forwarding rules.

    Is there still anything that you could point me to that i might do wrong?
    I it’s more convenient i can also contact you via discord

  9. Hi, thank you for the detailed tutorial.. It is very helpful however I am stuck in one point. I followed all the steps and redo it several times. I do not get any errors but I do not see an entry in Traefik. Everything looks working except the URL entry so can you please help me identify what am I doing wrong?

    1. Sure. Were you able to get Nextcloud app running? The entry will be automatically added in Traefik once the app is successfully started (and Ingress is setup correctly as well). I would say first make sure “enable Ingress” is checked in Nextcloud setting tab. My ID is windsketch#3025 and if you would like to we can have a quick talk on discord.

Leave a reply (please do not include URL in reply)