Nextcloud Deployment
Support and documentation for applications within the Stable catalog is handled by the TrueNAS community. The TrueNAS Applications Portal hosts but does not validate or maintain any linked resources associated with this app.
We welcome community contributions to keep this documentation current! Click Edit Page in the top right corner to propose changes to this article.
Nextcloud is a drop-in replacement for many popular cloud services, including file sharing, calendar, groupware, and more. One of its more common uses for the home environment is serving as a media backup, and organizing and sharing service.
Nextcloud 24 introduced support for handing off image preview thumbnail generation to an external service, Imaginary, a small HTTP server written in GO. It receives images over a REST API. Imaginary can upscale, downscale, crop, or resize images. TrueNAS Nextcloud app users can include Imaginary in their app deployment.
This procedure demonstrates how to set up Nextcloud on TrueNAS and configure it to support hosting a wider variety of media file previews, including High-Efficiency Image Container (HEIC), MP4, and MOV files. TrueNAS Nextcloud app postgres options include a postgres image selector and data storage volume. TrueNAS Nextcloud app provides backward compatibility and migration of early deployments of Nextcloud.
TrueNAS offers one deployment option for setting up Nextcloud, a Linux Debian-based TrueNAS version application available in TrueNAS releases 24.10 and later. The instructions in this article apply to these TrueNAS 24.10 and later releases.
Before you install the Nextcloud app:
Set a pool for applications to use if not already assigned.
You can use either an existing storage 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 a new TrueNAS user account to manage this application. When creating a new user account to manage this application or using an existing TrueNAS administrator account, enable sudo permissions for that TrueNAS user account, select Create New Primary Group, and add the appropriate group in the Auxiliary Group for the type of user you want to create. Make note of the UID for the new user to add in the installation wizard.
Add the user ID to the dataset ACL permissions when setting up app storage volumes in the Install app wizard.
(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.
When storage volumes include a postgres dataset, do not select Enable ACL to configure permissions. Instead, proceed with entering or browsing to select the dataset and populate the Host Path field, then select the Automatic Permissions option. This configures permissions for the postgres dataset and, if configured, the parent dataset used to organize required datasets for the app.
As with other host path storage volumes, you can create a dataset when entering the host path.
You can use Enable ACL to manually configure ACL permissions for the postgres dataset and a parent dataset, but the process is involved and you receive errors after clicking Install on the application installation wizard. Additionally, the Automatic Permissions option does not show on the wizard screen.
You can reverse setting the host path with Enable ACL selected and configuring ACE entries up to the point where you click Install to finish the installation. After this and when you receive the error, untangling permissions issues for the parent and postgres datasets gets complicated. We recommend you use the Automatic Permissions option.
Create a self-signed certificate for the app (if required).
- Set up a Nextcloud account. If you have an existing Nextcloud account, you enter the credentials for that user in the installation wizard. If you do not have an existing Nextcloud account, you can create one using the application install wizard.
This basic procedure covers the required Nextcloud 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).
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.
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.
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.
Next, enter the Nextcloud Configuration settings.
For a basic installation, you can accept default values, but enter the following values:
Enter the name of the administration user in Admin User and Admin Password.
If using an existing Nextcloud account, enter the administration credentials for that account or enter new to create new Nextcloud user account credentials. Select the APT packages you want to use. Nextcloud requires ffmpeg and smbclient. Click Add to the right of APT Packages twice to add two sets of Package fields.
Select ffmpeg in one, and smbclient in the other.
If selecting ocrmypdf, also set the Tesseract Language Codes option to use.
Click Add to show the Language field then enter either chi-sim for simplified Chinese or eng for English.
See Nextcloud Configuration Settings below for more information. Enter either the fully qualified domain name or the IP address and port for your TrueNAS system in Host as ##.###.###.##:port or my.domain.com:port.
The Data Directory Path is pre-populated with the correct path. Enable Imaginary if you want to use this option to modify images. Enter a password in Redis Password to create a new credential or enter the existing password if you already have Redis configured in your Nextcloud account.
Enter a password in Database Password to create a new credential for the Nextcloud database or enter the existing password if you already have the Nextcloud account database configured. Nextcloud does not URL encode in some places so do not use the ampersand (&), at (@), hashtag (#), or percent (%) characters in the Redis password. Accept the remaining defaults in the Nextcloud Configuration section. However, if you are setting up a cron job schedule, select Enabled under Cron to show the settings that allow you to schedule a cron job. The TrueNAS app is configured with all the required environment variables, but if you want to customize the container, click Add to the right of Additional Environment Variables for each to enter the variable(s) and values(s).Entering Nextcloud Configuration Settings
Enter the network configuration settings. Accept the default port, 30027, in WebUI Port, or enter an available port number of your choice. See Network Configuration below for more information on changing the default port. This port must match the one used in Host above.
If you configured a certificate for Nextcloud, select it in Certificate ID. A certificate is not required unless you want to use an external port other than the default 30027.
Add your Storage Configuration settings.
Do not select DEPRECATED: Old Storage Structure if you are deploying Nextcloud for the first time as this slows down the installation and is unnecessary. If you are upgrading where your Nextcloud deployment in TrueNAS was a 1.x.x release, select this option.
Set Type to Host Path (Path that already exists on the system) for AppData Storage. Select Enable ACL, then enter or browse to select the html dataset to populate the Host Path field.
Click Add to the right of ACL Entries for each user or group entry you want to add. Set ID Type to Entry is for a USER, enter the 0 in ID, and give it full control permissions. For example, add the 0 user, and give each FULL_CONTROL Access. Repeat this for the 568 user.
Select Force Flag to allow upgrading the app when the dataset has existing data.
Repeat the storage steps above to configure the host path for Nextcoud Data Storage. Enter or select the data dataset.
To configure the Nextcloud Postgres Data Storage host path, do not select Enable ACL! Set Type to Host Path (Path that already exists on the system), then enter or browse to select the postgres_data dataset to populate the Host Path field. Select Automatic Permissions. This does not show if you selected Enable ACL.
See Storage Configuration Settings below for more information.
Accept the defaults in Resources Configuration, and select the GPU option if applicable.
Click Install. A progress dialog displays before switching to the Installed applications screen. The Installed screen displays with the nextcloud app in the Deploying state. Status changes to Running when ready to use.
Click Web UI on the Application Info widget to open the Nextcloud web portal sign-in screen.
The following section provides more detailed explanations of the settings in each section of the Install installation wizard.
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.
Nextcloud configuration settings include setting up credentials, APT packages (previously referred to as the commands), the host IP and port, data directory path, upload limits, execution times, memory limits and cache memory consumption, adding a cron job with schedule, and adding additional environment variables.
If you have an existing Nextcloud account add the credentials for that account in the Admin User and Admin Password fields. If you do not have an existing account enter the name and password you want to use to create the Nextcloud login credentials.
Adding APT Packages
Nextcloud has three APT package options:
- ffmpeg
- smbclient
- ocrmypdf
You must add both the ffmpeg and smbclient packages to deploy this app.
You can also use ocrmypdf if needed, but you must select the Tesseract Language Code. Options are chi-sim for Simplified Chinese or eng for English. For more information on tesseract languages to install for OCRmypdf, see here for a list of language codes. Entering the wrong language code prevents the container from starting. Only takes effect if ocrmypdf is selected.
Click Add to the right of APT Packages for each option you want or need to add.
To configure the Host, enter the IP address for the TrueNAS system where you install the Nextcloud app and the web port number separated by a colon. For example, 12.123.12.3:30027. 30027 is the default port assigned to the TrueNAS Nextcloud app deployment. See Network Configuration for more information on this port assignment and how to change it.
Data Directory Path shows the data directory where Nextcloud stores all files from the users. It is prepopulated with /var/www/html/data which is the default path inside the container. We recommend not changing this path.
Nextcloud Redis requires a password for access. If you have an existing Nextcloud account with Redis configured, enter that existing password here but if not, enter a password to use for Redis in Nextcloud. Nextcloud also requires a password to secure access to the database. If you have an existing Nextcloud account database with a password configured, enter it Database Password. Enter a new password if you do not have an existing database password. The default value is nextcloud. The TrueNAS Nextcloud app passes these passwords to Nextcloud.
The PHP Upload Limit (in GB) applies a timeout to the client_max_body size in nginx, and the post_max_size and upload_max_filesize in PHP. Accept the default.
The Max Execution Time (in Seconds) sets the maximum execution time for Nextcloud. The default is 30 seconds, but you can adjust this based on your needs.
The PHP Memory Limit (in MB) sets a memory limit on PHP. The default is 512, with a range of 128 to 4096.
The OP Cache Memory Consumption (in MB) sets the size of the memory cache consumption. The default is 128, with a range of 128 to 1024.
If enabled, Cron shows the Schedule option. The default value is */5 * * * *. Enter the schedule values to replace the asterisks based on your desired schedule.
Refer to Nextcloud documentation for more information on environment variables.
The default web port for Nextcloud is 30027.
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.
To use a certificate, best practice is to create the self-signed certificate before you begin using the app installation wizard. If you did not create a certificate before starting the installation wizard you can select the default TrueNAS certificate and edit the app to change the certificate after deploying the application.
Select the certificate created in TrueNAS for the app from the Certificate dropdown list.
TrueNAS provides two options for storage volumes: ixVolumes and host paths.
Nextcloud needs three datasets for host path storage volume configurations:
- html to use as the AppData storage volume.
- data to use as the User Data storage volume.
- postgres_data to use as the Postgres Data storage volume.
If you nest these datasets under a parent dataset named nextcloud, you can create this nextcloud dataset with the Dataset Preset set to Generic or Apps. You can configure the ACL for this dataset from the Permissions widget on the Datasets screen. If the app has postgres storage volumes, the process is easier and less prone to permissions errors if you use the Automatic Permissions option in the postgres storage volume section of the install Wizard.
You can configure ACL permissions for the required dataset in the Install Nextcloud wizard, or from the Datasets screen any time after adding the datasets.
Creating App Datasets
To create the Nextcloud app datasets, go to Datasets, select the dataset you want to use as the parent dataset, then click Add Dataset. In this example, we create the Nextcloud datasets under the root parent dataset tank.
Enter nextcloud in Name, and select Apps as the Dataset Preset. Click Advanced Options if you want to make any other setting changes. Click Save. When prompted, select Return to Pool List to configure permissions later after adding the other three datasets, or open the ACL editor to edit ACL permissions immediately after adding the dataset.
Next, select the nextcloud dataset, and click Add Dataset to add the first child dataset. Enter html in Name and select Apps as the Dataset Preset. Click Advanced Options if you want to make any other setting changes. Click Save.
Repeat this two more times to add the other child datasets to the nextcloud parent dataset. When finished you should have the nextcloud parent dataset with three child datasets under it. Our example paths are:
- */mnt/tank/nextcloud/*html
- */mnt/tank/nextcloud/*data
- */mnt/tank/nextcloud/*postgres_data
Select Enable ACL to show the ACL and ACE Entries options for host path volumes except for postgres storage volumes. 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 for the run as users. The run-as user(s) show on the app details screen in the Run As Content widget, and on the Installed application screen after the app deploys.
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.
Postgres storage volumes have 999 as the default user ID and 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, set the Access permissions level to FULL CONTROL.
Do not use the Edit ACL option for postgres storage volumes. Select the Automatic Permissions option, which correctly sets permissions for the postgres and parent dataset (if used).
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.
TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod.
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.
TrueNAS Additional Storage options include the ability to mount an SMB share inside the container pod.
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.
The Labels Configuration settings allow users to configure Docker object labels to add metadata to containers. Docker object labels attach key-value metadata to various Docker objects, such as containers, images, volumes, and networks. Labels are useful for organization, automation, and providing additional context for Docker resources. They can store information such as environment details, ownership, service role, or custom tags for automation tools.
Click Add to display a set of label configuration fields.
Use Key to define the identifier that categorizes and filters resources, for example com.example.owner. Use Value to enter the associated data for the container, for example team-a.
Select the target container from the Containers dropdown list to apply the label(s). Apps with multiple containers list each container as an option on the dropdown.
Click Add again to configure additional labels.
Tips for Labels:
- Docker recommends using reverse-DNS notation to prevent conflicts with other objects.
- Use a consistent naming convention for labels applied across all containers, for example, com.example.owner=team-a, com.example.owner=team-b, com.example.env=production, com.example.env=testing.
- Use in groupings, for example, when applying configuration changes where labels define or group related database resources (com.example.role=db).
- Use reverse-DNS notation to prevent conflicts with other objects, as recommended by Docker.
- Use a consistent naming convention for labels applied across all containers, for example, com.example.owner=team-a, com.example.owner=team-b, com.example.env=production, com.example.env=testing.
- Use in groupings, for example, when applying configuration changes where labels define or group related database resources (com.example.role=db).
- Combine labels for more granular control, for example, using com.example.env=prod and com.example.tier=frontend to distinguish frontend from backend services in production environments.
Accept the default values in Resources Configuration or enter new CPU and memory values. By default, this application is limited to use no more than 2 CPU cores and 4096 megabytes available memory. The application might use considerably less system resources.
To customize the CPU and memory allocated to the container the app uses, enter new CPU values as a plain integer value (letter suffix is not required). The default is 4096.
Accept the default value (4 Gb) allocated memory or enter a new limit in bytes. Enter a plain integer without the measurement suffix, for example, 129 not 129M or 123MiB.
GPU Configuration provides the option to enable GPU passthrough. Select Passthrough available (non-NVIDIA) GPUs or, if your system has an NVIDIA GPU device, select Use this GPU.
For more information on GPU passthrough, see TrueNAS Apps.
Users can use Collabora and Nextcloud together. Collabora allows users to open and edit documents stored in their Nextcloud account. This integration allows users to edit a document simultaneously while providing live comments, suggestions, and version histories.
Users with Collabora and Nextcloud applications installed in TrueNAS can access the Nextcloud UI Apps section to find the Collabora Online application.
After installing Collabora Online, navigate to the Collabora Online tab in Nextcloud and enter your Collabora server address in the Collabora Online server field. This integrates Collabora and Nextcloud accounts, enhancing document access and editing capabilities.
For more details on installing Collabora, visit the Collabora TrueNAS tutorial.
If the app shows errors and does not deploy, the traceback should provide information on where the problem lies. If you opted to manually configure ACLs for a parent dataset and the storage volumes, or you did not select Automatic Permissions for the postgres storage volume configuration, opting instead to select Enable ACL and manually adding ACL entries, you might have the parent dataset and postgress storage volume permissions incorrectly set. In this scenario, you might need to add the www-data user and group (33:33) or some other user specified in the traceback to the nextcloud dataset. Do not set recursive for this user.
To avoid this problem, select Automatic Permissions for the postgres host path storage volume before you click Install in the wizard.
If you are deploying the app for the first time and encounter this error, you can delete all datasets, recreate them, and then configure the app installation wizard again. This removes any permissions issues with the deleted datasets.
You can also try to reset all permissions on the original datasets until the app installs without errors. Stop the app before editing the ACL permissions for the datasets.
Add the www-data user and group, or the one specified in the traceback, to the parent, html, and data datasets. Do not set the parent dataset to recursive. You can set recursive on the data and html datasets, but it is unnecessary. To do this:
- Select the dataset, scroll down to the Permissions widget, click Edit to open the ACL Editor screen.
- Click Add Item, select User in Who and www-data in the User field, and select Full Control in Permissions.
- Add an entry for the group by repeating the above steps but select Group.
- Click Save Access Control List.
Finally, add the user netdata and group docker (999:999) to the Postgres Data dataset, following the same process. Within the postgres container, the user and group 999 map to postgres.