How to run Nextcloud on Unraid

I recently setup a Nextcloud instance on Unraid using the Nextcloud Docker image, using PostgreSQL as the database. Though I have never used Nextcloud in the past, I'm quite experienced with Unraid, Docker and web servers. Despite my experience, I encountered a few irritating issues that required me to dig a little deeper than I normally do for other images I've used.

This guide discusses:

• How to configure the Nextcloud Docker image using Unraid
• How to link the Nextcloud Docker image to a separately-running PostgreSQL database
• (BONUS) Addressing one cause of the cryptic "Internal server error" stemming from Apache web server

This guide will not cover anything related to proxies; simply a "get up-and-running" guide that can hopefully be used as a starting point. This should (hopefully) result in a setup that can be further configured with more advanced settings and infrastructure with as little pain as possible.

This section title links to the Docker image I used to get the application up and running. This guide assumes you're using the same image.

There is a lot of information on this page, but most of it is not necessary for the purposes of simply getting up-and-running. The main variables to consider (if you're using PostgreSQL as your back end) are:

• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_HOST

Additionally, make note of the volumes that this container uses. I strongly recommend mapping a volume for every possible location that the image exposes. If you map these volumes, it makes it easy to do things like configure your app, manage custom apps, and view server logs. The volumes are:

• /var/www/html - where the app code lives
• /var/www/html/custom_apps - where custom apps go
• /var/www/html/config - config files (and examples of config files provided by the image)
• /var/www/html/data - where app data lives (most-importantly, where the nextcloud.log file is located)

Each of these locations will need to be mapped to a volume on your host machine in order to keep any changes you make to their contents.

The PostgreSQL image I am using is simply the official Postgres image. However, the version you use is extremely important; the latest version of postgres (as of 12/3/2023) will NOT work as the data source for Nextcloud. If you ignore this, you will likely encounter a cryptic "Internal Server Error" without a request ID or accompanying server logs (more on that below).

I'll try and provide an update later with more information on which versions actually are supported, but I can say for sure that as of writing this article, you can safely use postgres:10.12-alpine to get up and running on Nextcloud version 27.1.4.

Now that you're familiar with the Docker images used for this guide, the next step is configuring Unraid to run them with the correct settings. If you aren't familiar with Docker or Unraid, this can be especially troublesome since the Docker Hub documentation only covers how to run the containers from the command line.

This section assumes you're familiar with enabling and using the Docker service on Unraid, at a minimum. While this is not covered in this guide, that information should be relatively easy to track down elsewhere online.

You should start by creating the Postgres container so that it's already up-and-running prior to starting the Nextcloud instance, that way you can simply start the Nextcloud container once you're done configuring it (instead of having to wait until you go back and create the Postgres container). Nextcloud will fail to start correctly and revert to defaults if the expected database is not available.

Click the "Add Container" button to get to add a new container; you should end up in the following screen:

• Set "Name" to whatever you'd like
• Set "Repository" to postgres:10.12-alpine
  • Do not use the latest version of Postgres; it does not work with Nextcloud 27.1.4
• Leave the remaining settings alone

This will bind the service running in the container to a port on the host machine, so that the PostgreSQL database is available at <UNRAID_HOST_IP>:<PORT>.

1. Click the "+ Add another Path, Port, Variable, Label or Device" link above the Apply/Done buttons
2. Set the "Config Type" to Port
3. Set the "Name" field to something useful; I suggest "DB Port" or similar
4. Set "Container" port to 5432
   1. Must be set to 5432; the port it's running on within the container
5. Set the "Host" port to the port you want the service bound to on your host machine
   1. Can be any port that's not already in use on your host machine
6. The remaining fields can be left as-is
7. Click "Save"

Next, add the PostgreSQL-related variables. Follow these steps for each variable you need to add (repeat these steps for each variable listed below):

1. Click the "+ Add another Path, Port, Variable, Label or Device" link above the Apply/Done buttons
2. Set the "Config Type" to Variable
3. Set the "Name" field to something useful (or just use the same thing used for "Key")
4. Set the "Key" and "Value" as-needed for each variable that you need to add
   1. The remaining fields are optional

The variables you need are:

• POSTGRES_USER
  • Value: admin username (will result in a user with this username being created and set to admin)
• POSTGRES_PASSWORD
  • Value: admin password

There is only one path to add for Postgres; this is where it stores all of the data on your host machine. Do not skip this. If you don't set this, data will not persist if you restart the container.

1. Click the "+ Add another Path, Port, Variable, Label or Device" link above the Apply/Done buttons
2. Set the "Config Type" to Path
3. Set the "Name" field to something useful
4. Set the "Container Path" to /var/lib/postgresql/data
5. Set the "Host Path" to wherever you intend to store the corresponding files on the host machine
6. The remaining fields can be left as-is
7. Click "Save"

At this point, when you start the container, it should be ready to accept connections and persist all data changes.

Unless you're using the same value for both the POSTGRES_USER in the Postgres container and POSTGRES_DB in the Nextcloud container, you need to create the database you intend to use in your Postgres container. To do this, you just need to use any client that can connect to a PostgreSQL database, connect to your database, and run the following SQL query:

CREATE DATABASE nextcloud;

This will create a database named nextcloud; whatever you set your database name as in this step (in this case, nextcloud) will be the value for the POSTGRES_DB variable in the Nextcloud container.

If you use the same value for both POSTGRES_USER and POSTGRES_DB, then you won't need to manually-create the database like this; the Postgres container creates a database named after the user specified for the POSTGRES_USER variable (the admin user), meaning you don't need to create the database since it already exists.

Click the "Add Container" button to get to add a new container; you should end up in the following screen:

• Set "Name" to whatever you'd like
• Set "Repository" to nextcloud
• Leave the remaining settings alone

DO NOT CLICK "APPLY", YET; you need to add the appropriate port, paths, and variables in order for your Nextcloud instance to work properly. While the container will probably start in this state, it will be in a state of limited functionality.

This will bind the service running in the container to a port on the host machine, so that the Nextcloud service is available at <UNRAID_HOST_IP>:<PORT>.

1. Click the "+ Add another Path, Port, Variable, Label or Device" link above the Apply/Done buttons
2. Set the "Config Type" to Port
3. Set the "Name" field to something useful; I suggest "Application Port" or similar
4. Set "Container" port to 80
   1. Must be set to 80; the port it's running on within the container
5. Set the "Host" port to the port you want the service bound to on your host machine
   1. Can be any port that's not already in use on your host machine
6. The remaining fields can be left as-is
   1. Setting a "Default Value" can be done as a safety measure; without it, there is no port mapping if you forget to set this value
   2. Forgetting to set the port mapping will mean the Nextcloud service is not accessible on any port of the host machine
7. Click "Save"

Once you've configured the port and saved your changes, the configuration should look similar to the following:

Next, add the PostgreSQL-related variables. Follow these steps for each variable you need to add (repeat these steps for each variable listed below):

1. Click the "+ Add another Path, Port, Variable, Label or Device" link above the Apply/Done buttons
2. Set the "Config Type" to Variable
3. Set the "Name" field to something useful (or just use the same thing used for "Key")
4. Set the "Key" and "Value" as-needed for each variable that you need to add
   1. The remaining fields are optional
5. Click "Save"

This is how the Unraid UI should look, in a fresh state:

For a PostgreSQL-backed Nextcloud instance, the variables you need are:

• POSTGRES_DB
  • Value: Name of the database to use; use whatever name you used for the database you created manually after you added the Postgres container
• POSTGRES_USER
  • Value: username of the "nextcloud" database user; can be the admin user of the DB for simplicity, otherwise you'll need to create the user/password and use those values
• POSTGRES_PASSWORD
  • Value: password of the "nextcloud" database user; can be the admin user of the DB for simplicity, otherwise you'll need to create the user/password and use those values
• POSTGRES_HOST
  • Value: Address of the PostgreSQL database

First, a warning; there is no such thing as "paths" (as a feature concept) in Docker. "Paths", as Unraid calls them, correspond to Docker Volumes. A volume is basically just a directory on the host machine that's linked to some directory within a running Docker container. It allows you to persist changes between runs of the Docker container that would otherwise start "fresh" each time the container is restarted.

In Nextcloud's case, this gives you a way to do things like make changes to your Nextcloud configuration and have it persist between each run.

Follow these steps for each Path you need to add (repeat these steps for each path listed below):

1. Click the "+ Add another Path, Port, Variable, Label or Device" link above the Apply/Done buttons
2. Set the "Config Type" to Path
3. Set the "Name" field to something useful
4. Set the "Container Path" to whichever path you're targeting within the container
5. Set the "Host Path" to wherever you intend to store the corresponding files on the host machine
6. The remaining fields can be left as-is
7. Click "Save"

This is how the Unraid UI should for adding a Path, in a fresh state:

Create a Path configuration for each of the following container paths:

• /var/www/html
• /var/www/html/custom_apps
• /var/www/html/config
• /var/www/html/data

I recommend grouping them all to a common location, such as /mnt/user/nextcloud. For example, set the "Host Path" to /mnt/user/nextcloud/config for the /var/www/html/config container path.

At this point, and assuming the Postgres container is running, you should be able to start the container and connect to it via the IP of the machine your Unraid instance is running and the port of the Nextcloud service.

Create an admin account and click "Install" (but beware that the install step takes some time; it might seem to hang). Once installation is complete, you're free to configure the application however you'd like!

This is a particularly annoying issue that I've seen many people face for a variety of reasons. People running their Nextcloud instance behind a proxy can hit this for reasons not covered in this guide - for those such users, I wish you luck and advise you reach out to the various communities that can help support your setup.

However, if you're just using a minimal setup as-described in this article (where it's pretty much just the Nextcloud container and it's supporting database container), this section may help you out.

For me, this issue started happening after I clicked the "Install" button when creating the Nextcloud admin account. After running for several minutes, the web page stopped and presented me with the following message:

For the sake of indexing, this is the error text:

Internal Server Error

The server encountered an error and was unable to complete your request.
Please contact the server administrator if this error reappears multiple times, please include the technical details below in your report.
More details can be found in the server log.

The problem is, there are no log entries related to this event in nextcloud.log. Additionally, there is no request ID like there normally would be for Nextcloud errors.

After much digging, I found that the message in the previous screenshot is something of a general "catch-all" error that happens when something goes wrong with an Apache web server. I don't work much with Apache web servers in my professional life, but I do work with other servers extensively; to me, this seemed like some kind of a setup issue, but without logs, I was not able to get concrete information on what was wrong.

It turned out, I was using "too new" of a version of Postgres.

When I first-created the Postgres container, I simply used postgres as the repository. This led to the image for the latest version of Postgres being used, which is apparently incompatible with Nextcloud 27.1.4. After setting the repository to postgres:10.12-alpine, I was able to get Nextcloud up and running without issue.

I assume there are other versions of Postgres that will work with Nextcloud 27.1.4, but at the time of writing, I am not aware of where any compatibility lists may exist. If I am able to find one, I will provide it here as an update.

I obviously can't address all issues that may get you into this state, but what I can say is that, should you get to this exact state, odds are good that you have a major setup issue to address. Start by checking the versions of all your dependencies to make sure you're using things that are compatible with Nextcloud - the trick is finding the compatibility lists for whatever it is you need. Best of luck!