TrueNAS AppsTrueNAS Apps: Tutorials
Application maintenance is independent from TrueNAS version release cycles.
App versions, features, options, and installation behavior at time of access might vary from documented tutorials and UI reference.

Setting Up MinIO Clustering

We welcome community contributions to keep this documentation current! Click Edit Page in the top right corner to propose changes to this article. See Updating Content for more information.

This article applies to the public release of the TrueNAS S3 MinIO stable train application configured in a distributed mode cluster.

TrueNAS 23.10 and later allows users to create a MinIO S3 distributed instance to scale out TrueNAS to handle individual node failures. A node is a single TrueNAS storage system in a cluster.

The stable train version of MinIO supports distributed mode. Distributed mode, allows pooling multiple drives, even on different systems, into a single object storage server. For information on configuring a distributed mode cluster in TrueNAS using MinIO, see Setting Up MinIO Clustering.

The enterprise train version of MinIO provides two options for clustering, Single Node Multi-Disk (SNMD) and Multi-Node Multi-Disk (MNMD) configurations. See MinIO Enterprise for more information.

The examples below use four TrueNAS systems to create a distributed cluster. For more information on MinIO distributed setups, refer to the MinIO documentation.

Before You Begin

Before you install the stable version of the MinIO app:

  • Set a pool for applications to use if not already assigned.

    You can use either an existing pool or create a new one. TrueNAS creates the ix-apps (hidden) dataset in the pool set as the application pool. This dataset is internally managed, so you cannot use this as the parent when you create required application datasets.

    After setting the pool, the Installed Applications screen displays Apps Service Running on the top screen banner.

  • Locate the run-as user for the app.

    Take note of the run-as user for the app, shown on the app information screen in the Run As Context widget and in the Application Metadata widget on the Installed applications screen after the app fully deploys. The run-as user(s) get added to the ACL permissions for each dataset used as a host path storage volume.

  • (Optional) Create datasets for the storage volumes for the app.

    Do not create encrypted datasets for apps if not required! Using an encrypted dataset can result in undesired behaviors after upgrading TrueNAS when pools and datasets are locked. When datasets for the containers are locked, the container does not mount, and the apps do not start. To resolve issues, unlock the dataset(s) by entering the passphrase/key to allow datasets to mount and apps to start.

    You can create required datasets before or after launching the installation wizard. The install wizard includes the Create Dataset option for host path storage volumes, but if you are organizing required datasets under a parent you must create that dataset before launching the app installation wizard.

    Go to Datasets and select the pool or dataset where you want to place the dataset(s) for the app. For example, /tank/apps/appName.

Create a parent dataset, such as minio, and then the storage dataset(s) (data, etc.) under it. Select apps as the Dataset Preset for these datasets. You can modify the dataset ACLs at the time of creation, or modify them later when adding them to the app.

Creating Datasets for Apps

When creating datasets for apps follow these steps:

  1. Go to Datasets, select the location for the parent dataset if organizing required datasets under a parent dataset, then click Add Dataset. For example, select the root dataset of the pool, and click Add Dataset to create a new parent called apps or appName*, where appName is the name of the app.

    Do not create the app datasets under the ix-applications or ix-apps dataset.

  2. Enter the name of the dataset, then select Apps as the Dataset Preset. Creating the parent dataset with the preset set to Generic causes permissions issues when you try to create the datasets the app requires with the preset set to Apps.

  3. Click Save. Return to dataset creation when prompted rather than configuring ACL permissions.

    You can set up permissions (ACLs) for a dataset after adding it by selecting Go to ACL Manager to open the Edit ACL screen, or wait and use the app Install wizard ACL settings to add permissions. You can also edit permissions after installing the app using either method.

  4. Select the parent dataset and then click Create Dataset to open the Add Dataset screen again.

  5. Enter the name of a dataset required for the app, such as config, select Apps as the Dataset Preset, and then click Save. When prompted, return to creating datasets rather than setting up ACL permissions.

  6. Repeat for remaining datasets required for the app.

If your system has active sharing configurations (SMB, NFS, iSCSI), disable them in System > Services before adding and configuring the MinIO application. Start any sharing services after MinIO completes the installation and starts.

  • Create a self-signed certificate for the app (if required).

Adding a certificate is optional, but if you want to use a certificate for this application, either create a new self-signed CA and certificate or import an existing CA and create the certificate for MinIO. A certificate is not required to deploy the stable train MinIO application.

Configuring MinIO in a Cluster

Begin on the first node (system) in your cluster.

Go to Apps, click on Discover Apps, and locate the app widget by either scrolling down to it or begin typing the name into the search field. For example, to locate the MinIO app widget, begin typing minIO into the search field to show app widgets matching the search input.

If this is the first application installed, TrueNAS displays a dialog about configuring apps.

Configuring Apps Dialog

Click Confirm then Agree to close the dialog and open the application details screen.

If not the first time installing apps the dialog does not show, click on the widget to open the app information screen.

Click Install to open the app installation wizard.

Application configuration settings are grouped into several sections, each explained below in Understanding App Installation Wizard Settings. To find specific fields begin typing in the Search Input Fields search field to show the section or field, scroll down to a particular section, or click on the section heading in the list of sections on the upper-right of the wizard screen.

MinIO Install Wizard Screen
Figure 5: MinIO Install Wizard Screen

Accept the default value or enter a name in Application Name field. In most cases use the default name, but if adding a second deployment of the application you must change this name.

Accept the default version number in Version. When a new version becomes available, the application shows an update badge and the Application Info widget on the Installed applications screen shows the Update button.

You can have multiple deployments of the same app (for example, two or more from the stable or enterprise trains, or a combination of the stable and enterprise trains).

Naming Multiple App Deployments

Each deployment of the same app requires a unique name. App names can include numbers, dashes, or underscores (for example, syncthing2, syncthing-test, syncthing_1, minio2, etc.).

Use a consistent file-naming convention to avoid conflict situations where data does not or cannot synchronize because of file name conflicts. Path and file names in apps are case-sensitive. For example, a file named MyData.txt is not the same as the mydata.txt file in Syncthing.

Next, enter the MinIO Configuration settings.

The MinIO wizard defaults include all the arguments you need to deploy a container for the application.

Enter a name in Root User to use as the MinIO access key. Enter a name of five to 20 characters in length, for example admin or admin1. Next enter the Root Password to use as the MinIO secret key. Enter eight to 40 random characters, for example MySecr3tPa$$w0d4Min10.

Refer to MinIO User Management for more information.

Keep all passwords and credentials secured and backed up.

MinIO containers use server port 9000. The MinIO Console communicates using port 9001.

You can configure the API and UI access node ports and the MinIO domain name if you have TLS configured for MinIO.

Add your Storage Configuration settings.

For a distributed cluster, ensure the values are identical between server nodes and that they have the same credentials.

MinIO Distributed Mode Settings
Figure 7: MinIO Distributed Mode Settings

MinIO uses one dataset, one ixVolume, and two mount paths. Leave the MinIO Export Storage (Data) set to the defaults, with Type set to ixVolume and the mount path /export. You can create a dataset for this and use the host path option but it is not necessary for this storage volume.

Add the storage volume for MinIO data storage. Click Add to the right of Additional Storage. Set Type to Host Path (Path that already exists on the system). Enter /data in Mount Path, select Enable ACL, then enter data in Dataset Name.

Click Add to the right of ACL Entries to show the permissions fields. Set Id Type to Entry is for a USER, enter 473 in ID, and give it full permissions. Repeat for the /data storage volume.

Data Host Path ACL and ACE Settings
Figure 8: Data Host Path ACL and ACE Settings

Accept the default values in Resources Configuration.

Click Install.

The Installed applications screen opens showing the application in the Deploying state before it changes to Running when the application is ready to use.

Click Web Portal to open the MinIO sign-in screen.

After completing the first node, begin configuring the remaining system nodes in the cluster (including datasets and directories).

After installing MinIO on all systems (nodes) in the cluster, start the MinIO applications.