[Guide] Building and Running Custom Docker Applications on TrueNAS SCALE

[Constantin.FF]

This is guide on how I set up my Scale to build and run custom projects.
I use it to run Nodejs, PHP and some linux bash scripts and GUI apps with noVNC.

This is an alternative of using Github and Github Actions for the build and DockerHub for you images.

Prerequisites:

1. Ensure you have the TrueCharts apps catalog set up. If not, follow this guide:
   

   Getting Started with TrueCharts | TrueCharts

   Below you'll find recommended steps to go from a blank or fresh TrueNAS SCALE installation to using TrueCharts with the best possible experience and performance as determined by the TrueCharts team. It does not replace the application specific guides and/or specific guides on certain subjects...

   truecharts.org
2. (Optional) If you plan to use your own domain for your apps (e.g., "portainer.example.com", "git.example.com")
   Install cert-manager and clusterissuer
   

   clusterissuer Setup Guide | TrueCharts

   This guide will walk you through setting up clusterissuer, certificate management for Kubernetes.

   truecharts.org
   Install Traefik
   

   TrueNAS Web GUI via Traefik | TrueCharts

   If you followed the instructions in Installing Traefik, your TrueNAS Web GUI will now be served on custom ports (port 81 and 444 in the video guide).

   truecharts.org

Step 1: Install Gitea
Before installing Gitea, make sure you have these apps installed: cloudnative-pg and prometheus-operator.
Install Gitea with the recommended settings.

Step 2: Installing Portainer
The default Portainer install only provides access to the Kubernetes cluster. To gain access to Docker as well, follow these steps:

1. Mount the docker.sock into the container to access Docker directly:
   
   Code:

      [Additional App Storage]
      Type of Storage: Host Path
      Host Path: /var/run/docker.sock
      Mount Path: /var/run/docker.sock

2. Change "runAsGroup" to get access to docker
   
   Code:

      [Security Context]
      runAsGroup: 999 (the "docker" group on SCALE).

3. For proper project cloning and running in Portainer some additional settings are required.
   The actual discussion for this issue is here: https://github.com/orgs/portainer/discussions/9795
   Ensure these three paths settings are the same.
   
   Code:

   [Extra Args]
   --data=/mnt/pool-1/portainer/data
   [Additional App Storage]
   Type of Storage: Host Path
   Host Path: /mnt/pool-1/portainer/data
   Mount Path: /mnt/pool-1/portainer/data

Step 3: Adding Docker Sock in Portainer

1. Log into the Portainer instance.
2. Upon the first run, you'll be prompted to add the "local" Kubernetes cluster. Proceed with it.
3. Navigate to Environments -> + Add Environment
4. Choose Docker Standalone and select Start Wizard
5. Select Socket, then provide a name for the environment.

Step 4: Testing Your Setup

1. From the Home screen, select your Docker environment.
2. Access Stacks and click + Add Stack
3. Choose Repository if you want code pulled from Gitea or GitHub.
4. Configure other settings based on your project's requirements.

Final Steps: Accessing Your App
With everything set up, Portainer should now clone your code and run Docker Compose. If you've exposed ports in your docker-compose.yml file, you can access your app using your TrueNAS IP together with your app exposed port.

To-Do List:

1. Explore the possibility of building Docker containers in Portainer and using them in SCALE Apps, either through "Launch Docker Image" or TrueCharts "custom-app".
2. Include screenshots

Troubleshooting:

1. If you encounter issues while running Gitea with CloudNative-PG (CNPG), refer to this useful link.
   https://truecharts.org/manual/FAQ#how-do-i-stop-a-truecharts-app-truenas-scale-only

 

[JeanCFS]

Thank you very much for the excellent tutorial. I was having trouble setting up Portainer + Docker on TrueNAS Scale, and your guide solved my problem.

 

[hogen]

Thank you! This tutorial is indeed excellent. The Portainer part was just what i needed. I now have Gramps docker setup running with my own domain and cert too. I will link to this tutorial in their forum since there is no real kubernetes support yet.

Maybe add after the "Final steps" as optional that a external-service app is used for each container you want to have a traefik ingress domain. And refer to the the second prerequisite. https://truecharts.org/manual/SCALE/guides/truenas-web-gui-via-traefik

I dont think there is any need for screenshots for this.

 

[dibun]

In my installation there is no /var/run/docker.sock file and I have installed cloudnative-pg, prometheus-operator and Gitea

 

[newguy123]

In my installation there is no /var/run/docker.sock file and I have installed cloudnative-pg, prometheus-operator and Gitea

same

 

[majorgear]

Is there a solution that doesn’t use TrueCharts?

 

[hogen]

In my installation there is no /var/run/docker.sock file and I have installed cloudnative-pg, prometheus-operator and Gitea

@Constantin.FF is yours working? Mine stopped after upgrade to Cobia 23.10,

 

[Neopegasus]

Hi all, I try this Guide and I run in a couple of problem:

• /var/run/docker.sock do not exist
• cert-manager seems that you already have it or there something is not good.
• after installing cloudnative-pg, prometheus-operator, gitea and portainer the system went really unstable

is this guide outdated already?

I am running: TrueNAS-SCALE-23.10.1

Best regards

 

[AirborneTrooper]

Cobia removed docker. Is there any work around to get portainer running local instead of kubernetes?

 

[plinsboorg]

Same for me. It stopped working after the update, and /var/run/docker.sock do not exist.
Please, anyone, help to make the Portainer work again for Cobia...

 

[AirborneTrooper]

Same for me. It stopped working after the update, and /var/run/docker.sock do not exist.
Please, anyone, help to make the Portainer work again for Cobia...

I ended up installing debian VM and run docker there. There’s a good YouTube video to help set it up where docker on your VM stores on a share.

 

[Supertorben]

My TrueNAS-SCALE-23.10.1 also have no docker.sock because it is using containerd as a backend. this is more lightweight and reliable in enterprise setups than docker and also in most Project the preferred backend.

Question is if portainer will or is supporting containerd as a backend instead of docker.