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.

MinIO

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.

MinIO High Performance Object Storage, released under the Apache Licenses v2.0 is an open source Amazon S3 cloud storage compatible object storage solution. The TrueNAS MinIO applications allow users to build high-performance infrastructure for machine learning, analytics, and application data workloads.

TrueNAS has two versions of the MinIO application, a stable and enterprise train version. The tutorials in this section cover installing the TrueNAS stable train version of the MinIO.

The smaller MinIO enterprise train version of the application is tested and polished for a safe and supportable experience for TrueNAS Enterprise customers. Community members can install either version of this application.

Adding the MinIO (Enterprise) App

To add the Enterprise MinIO application to the list of available applications:

Go to Apps, click on Configuration at the top of the Installed applications screen, and select Settings to open the train Settings screen.

You can also access the Installed scren from the Discover screen by clicking on Manage Installed Apps at the top of the screen.

Select enterprise to add it to the list of trains, and then click Save.

After changing train settings, return to the Discover screen and click Refresh Catalog.

Both the stable and enterprise train versions of the MinIO app widget display on the Discover application screen.

DiscoverScreenMinIOAppWidgets

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.

  • 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.

    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.

Installing MinIO (S3) App

This procedure covers the basic requirements and installation and configuration instructions for the stable train version of the MinIO application. For instructions on installing the Enterprise version of the MinIO application see Configuring Enterprise MinIO.

This basic procedure covers the required MinIO app settings. For optional settings, see Understanding App Installation Wizard Settings.

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.

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 6: 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.

Select Enable Distributed Mode if you are setting up MinIO in a cluster configuration.

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.

Understanding App Installation Wizard Settings

The following sections provide more detailed explanations of the settings in each section of the Install MinIO configuration screen.

Application Name and Version Settings

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.

MinIO Configuration Settings

MinIO configuration settings include setting up credentials and adding additional environment variables.

MinIO credentials establish the login credentials for the MinIO web portal and the MinIO administration user. Enter existing MinIO credentials if you already have a MinIO account, or create new login credentials for the first time you log into MinIO.

MinIO Configuration Settings
Figure 11: MinIO Configuration Settings

Enter a username for the root user (MinIO access key) in MinIO Root User that is limited to five to 20 characters long. For example admin or admin1.

Enter the root user password (MinIO secret key) in MinIO Root Password. The password is limited to 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.

Adding Environmental Variables

The app is preconfigured with the arguments needed to deploy a container. The Extra Arguments and Extra Environment Variables settings are not required to deploy the application. Do not enter the server and URL argument required in earlier app versions.

The app wizard is configured with all settings required to deploy the container, but you can add additional settings if you want to further customize the app in TrueNAS.

Click Add to the right of Environmental Variables to show a set of fields to configure the application with additional variables.

You can add environment variables to the app configuration after deploying it. Click Edit on the Application Info widget for the app found on the Installed Application screen to open the edit screen.

User and Group Configuration Settings

MinIO User and Group Configuration Settings
Figure 13: MinIO User and Group Configuration Settings

Some TrueNAS apps have predefined run-as user and group IDs. These assignments vary based on the app train and other variables such as installing but not running as the root user.

Default user and group IDs are:

  • 473 for the MinIO stable train app.
  • 568 (apps user), used in some community apps and all apps in the enterprise train
  • 999 (netdata user), used for all postgres storage volumes
  • 0 (root user).

Accept the default user and group ID in the User and Group Configuration section or enter the user ID for a new TrueNAS user created to serve as the administrator for this app.

Create any app administrator user before installing the application, and take note of the UID. Enter this user ID when configuring the user for the app and as the user when setting up storage volume permissions.

Network Configuration

Network configuration settings set the port number to access the MinIO API and WebUI console ports. The default ports are 9000 for API port and 9002 for the console port

Network Configuration Settings
Figure 14: Network Configuration Settings

Accept the default port settings in Network Configuration.

All TrueNAS apps are assigned default port numbers. Accept the default port numbers, but if changing port number assignments, enter a number within the range 1-65535, however, 0-1024 might require the application to have elevated privileges. Before changing default ports, refer to the TrueNAS default port list for a list of assigned and available port numbers.

The app does not require configuring advanced DNS options. Accept the default settings or click Add to the right of DNS Options to enter the option name and value.

The Certificates setting is required when setting up multi-mode configurations in the Enterprise version of the MinIO app and when using MinIO as an immutable target for Veeam Backup and Replication. Certificates are optional for basic, non-cluster deployments of the MinIO app.

Adding an App Certificate
  1. Go to Credentials > Certificates to add a self-signed certificate authority (CA) and certificate for the application to use.

  2. Click Add on the Certificate Authorities (CA) widget to open the Add Certificate Authority screen.

    a. Enter a name for the CA. For example, minio, syncthing, etc. Accept the defaults for Type and Profile, then click Next.

    b. Accept the defaults on Certificate Options unless you want to set an expiration on the certificate. Enter a new value in Lifetime to impose an expiration time, then click Next.

    c. Enter location and organization values for your installation in the Certificate Subject fields. Enter the email address you want to receive system notifications.

    d. Enter your system IP address in Subject Alternate Names, then click Next. When configuring a multi-node multi-disk (MNMD) cluster, enter the system IP addresses for each system in the cluster.

    e. Accept the default values on Extra Constraints, then click Next.

    f. Review the CA configuration then click Save.

  3. Click Add on the Certificates widget to open the Add Certificate screen.

    a. Enter a name for the certificate. For example, minio, syncthing, etc. Select Internal Certificate as Type, HTTPS RSA Certificate in Profiles, then click Next.

    b. Select the newly-created CA in Signing Certificate Authority. Accept the rest of the defaults unless you want to set an expiration on the certificate. Enter a new value in Lifetime to impose an expiration time, then click Next.

    c. Enter location and organization values for your installation in the Certificate Subject fields. Enter the email address you want to receive system notifications.

    d. Enter your system IP address in Subject Alternate Names, then click Next. When configuring an MNMD cluster, enter the system IP addresses for each system in the cluster.

    e. Accept the default values on Extra Constraints, then click Next.

    f. Review the CA configuration then click Save.

  4. Download the certificate and install it.

    a. Click the download icon on the Certificates widget to start the download. If prompted to allow the download, click Allow. If prompted to keep, click Keep for both the .crt and .key files. When complete, open these files in a File Explorer window.

    b. Right-click on the certificate.crt file, click Open, then click Install Certificate to open the Certificate Import Wizard.

    CertificateOpenCertificateWindow

    c. Select Local Machine on the Welcome to the Certificate Import Wizard window. Click Next.

    CertificateImportWizardSelectLocalMachine

    If on a Windows system, allow changes to be made.

    d. Select Place all certificates in the following store, then select Trusted Root Certificate Authorities and click OK.

    SelelectCertificateStore

    c. Click Next then Finish.

Storage Configuration

Do not select Enable Distributed Mode unless setting up a cluster.

Select Enable Distributed Mode when setting up a cluster of TrueNAS systems in a distributed cluster.

MinIO in distributed mode allows you to pool multiple drives or TrueNAS systems (even if they are different machines) into a single object storage server for better data protection in the event of single or multiple node failures because MinIO distributes the drives across several nodes. For more information, see the Distributed MinIO Quickstart Guide.

To create a distributed cluster, click Add to show the Distributed MinIO Instance URI(s) fields for each TrueNAS system (node) IP addresses/host names to include in the cluster. Use the same order across all the nodes.

TrueNAS provides two options for storage volumes: ixVolumes and host paths. The MinIO Enterprise app uses host paths as the storage volume type. Only use ixVolumes for a test deployment of the MinIO app. MinIO uses an ixVolume for the /export mount path and storage volume by default. Create the data dataset to use as a host path storage volume, and accept the default /data as the mount path for this storage volume.

Setting the Storage Volume Type

To allow TrueNAS to create the storage volume, leave Type set to ixVolume (Dataset created automatically by the system). This adds a storage volume for the application nested in the hidden ix-apps dataset, located on the pool selected as the apps pool. Using ixVolume is intended for a test deployment of an app but not for a full app deployment, as data does not persist for these volumes after deleting the app where a dataset does. Datasets make recovering, transferring, and accessing app configuration, user, or other data possible where ixVolumes do not.

To use an existing dataset, which is the recommended option, set Type to Host Path (Path that already exists on the system).

If the install wizard shows a Mount Path, either accept the default value or enter the correct mount path. For example, if the dataset name is data, enter /data as the mount path.

To create a dataset while in the app installation wizard, with Type set to the host path option, go to the Host Path field, click into the pool or a dataset in the pool to activate the Create Dataset option. Click on Create Dataset to open the dialog. Enter the name for the dataset, then click Create. TrueNAS creates the dataset in the location selected.

Select Enable ACL to define ACL permissions and to populate the Host Path field by either entering or browsing to and selecting the location of the dataset. Populating the Host Path with the dataset location and then selecting Enable ACL clears the values, so we recommend selecting Enable ACL before entering the host path.

Repeat the above for each required dataset.

You can add extra storage volumes during the app installation, or edit the application after it deploys. Stop the app before editing settings.

Setting Dataset ACL Permissions

You can configure ACL permissions for the required dataset in the Install MinIO wizard, or from the Datasets screen any time after adding the datasets.

Select Enable ACL to show the ACL and ACE Entries options. Configure ACE entries for each UID and/or GID you recorded from the Run As Context widget in Before You Begin.

Configuring ACE Entries

Enter or browse to select the dataset and populate Host Path.

Next, click Add to the right of ACL Entries to show the permissions settings. Set ID Type to Entry is for a USER or Entry is for a GROUP. If you configured a group in TrueNAS that you want to give access to instead of a single user, set the ID to the group option and enter the GID for that group.

Enter the UID and/or GID as one of the following:

  • The default app user:
    • 568 for apps in all trains if the app can run as any non-root user.
    • 999 for all postgres storage volumes.
    • 0 if running as root.
    • 473 for MinIO app in the stable train.
  • The run-as-user UID set as a default for the app. The run-as user shows on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys. You can refer to the tutorial for the app, or look in the questions.yaml file found in the GitHub repository for the application to find this UID/GID.
  • The user ID for the new or existing TrueNAS user added to serve as the administrator for the app.

If the app shows User and Group Configuration settings, the default UID shows on the screen. If not, choose the run-as user ID found in the Run As Content widget.

Use the default user ID 999 for all postgres storage volumes, not the run-as user.

If you created a new TrueNAS user to serve as the app administration user, add an entry record and enter the UID for this user in addition to the run-as user ID.

When adding the ACL entry for the run-as user, default user, and/or optional TrueNAS app administrator user, and postgres user ID, set the Access permissions level to FULL CONTROL.

Select Force Flag to apply the ACL even if the path has existing data. This allows you to update the app when an update is available.

Adding ACL Permissions from the Datasets Screen First, select the dataset row, scroll down to the Permissions widget, and click Edit to open the Edit ACL screen. Change the @owner and @group values from root to the administrative user for your TrueNAS system, and click apply for each. Next, add an ACL entry for the run-as user. For Emby, the run-as users are 0 for root. Add a user entry for this user. Save the ACL before leaving the screen.

Mounting an SMB Share Storage Volume

TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod.

Configuring Additional Storage Volumes

If you choose to configure additional storage volumes, click Add to the right of Additional Storage to show the Type field with three options:

  • HostPath (Path that already exists on the system) requires an existing dataset.
  • ixVolume (Dataset created automatically by the system) creates a storage volume in the hidden ix-apps dataset.
  • SMB/CIFS Share (Mounts a volume to a SMB share) shows settings to create an SMB share storage volume. You must create the SMB share user and share dataset before adding this type.
  • Anonymous (Temporary directory created on the disk) creates a temporary directory in the hidden ix-apps dataset.
  • Tmpfs (Temporary directory created on the RAM) creates a temporary directory in RAM.

If adding an SMB share as an additional storage volume, create the SMB dataset and share user(s), and add the user ID for the share user(s) to the dataset ACL.

Set Type an SMB/CIFS Share (Mounts a volume to a SMB share) to add an SMB share storage volume.

Select Read Only to make the storage volume read only.

Enter the path inside the container to mount the storage for the share volume in Mount Path.

Enter the server address for the SMB share in Server, the path to mount the SMB share in Path, and the share authentication user credentials in User and Password. (Optional) enter the share domain name in domain.

Permissions are currently limited to the permissions of the user that mounted the share.

Use the SMB option for data synchronization between a share and the app if the option shows on the screen. A present, only the Syncthing app includes this option.

Resource Configuration

MinIO Resource Limits
Figure 18: MinIO Resource Limits

Contents

  • Setting Up MinIO Clustering: Provides configuration instructions using the MinIO Offical Charts application widget. It includes instructions on setting up a distributed cluster configuration.