Nextcloud¶

License: AGPLv3

This guide is tested with Nextcloud 32.0.5 on Uberspace 8.0.65. We can't guarantee it to work with newer versions.

Nextcloud is an open-source platform for hosting your own cloud for file storage, syncing, and collaboration. It provides features like file sharing, calendar, contacts, and document editing while keeping full control over your data. It’s ideal for those who prefer privacy, customization, and independence from large commercial cloud providers.

Nextcloud was initially released in 2016 as a fork of ownCloud and is maintained by Nextcloud GmbH.

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites¶

We're using PHP in the stable version 8.4:

[isabell@moondust ~]$ uberspace tool version set php 8.4
OK: Set version of php to 8.4

You'll need your MariaDB credentials:

[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword

Installation¶

Download¶

cd to your document root, download the latest Nextcloud release and extract it on the fly, omitting the top-level directory from the archive:

[isabell@moondust ~]$ cd /var/www/virtual/$USER/html/
[isabell@moondust html]$ rm nocontent.html
[isabell@moondust html]$ curl https://download.nextcloud.com/server/releases/latest.tar.bz2 | tar -xjf - --strip-components=1

Create the database¶

First, create a MariaDB database for your Nextcloud installation:

[isabell@moondust ~]$ mariadb --verbose --execute="CREATE DATABASE ${USER}_nextcloud"
--------------
CREATE DATABASE isabell_nextcloud
--------------

Run the installation script¶

Execute the Nextcloud maintenance script occ with the following parameters. Set these three values to your account-specific credentials before running the command:

NEXTCLOUD_ADMIN_USER — the admin username for your first login
NEXTCLOUD_ADMIN_PASS — the admin password
MARIADB_PASSWORD — your MariaDB password

[isabell@moondust ~]$ NEXTCLOUD_ADMIN_USER='MyUserName'
[isabell@moondust ~]$ NEXTCLOUD_ADMIN_PASS='MySuperSecretAdminPassword'
[isabell@moondust ~]$ MARIADB_PASSWORD='MySuperSecretMariaDBPassword'
[isabell@moondust ~]$ php occ maintenance:install --admin-user="${NEXTCLOUD_ADMIN_USER}" --admin-pass="${NEXTCLOUD_ADMIN_PASS}" --database='mysql' --database-name="${USER}_nextcloud"  --database-user="${USER}" --database-pass="${MARIADB_PASSWORD}" --data-dir="${HOME}/nextcloud_data"
Nextcloud was successfully installed

Configuration¶

PHP settings¶

To optimize Nextcloud performance, configure the following PHP settings.

OPcache caches script bytecode in shared memory, so scripts don't need to be loaded, parsed, and compiled on every request. Create the file ~/.config/php/opcache.ini with the following content:

opcache.enable=1
opcache.enable_cli=1
opcache.interned_strings_buffer=32
opcache.max_accelerated_files=10000
opcache.memory_consumption=256
opcache.save_comments=1
opcache.revalidate_freq=1

APCu is an in-memory key-value store for PHP. Create the file ~/.config/php/apcu.ini with the following content:

apc.enable_cli=1

Nextcloud recommends 512 MB of memory. Create the file ~/.config/php/memory_limit.ini with the following content:

memory_limit=512M

Disable output buffering by creating ~/.config/php/output_buffering.ini with the following content:

output_buffering=off

Restart PHP-FPM to apply the new configuration:

[isabell@moondust ~]$ systemctl restart --user php-fpm

Set the admin user email address¶

Set the email address of the admin user to enable sending emails and receiving administration notifications.

[isabell@moondust ~]$ php occ user:setting $NEXTCLOUD_ADMIN_USER settings email "$USER@uber.space"

Set the trusted domain¶

Add the domain you'll use to access Nextcloud as a trusted domain:

[isabell@moondust ~]$ php occ config:system:set trusted_domains 0 --value="${USER}.uber.space"
System config value trusted_domains => 0 set to string isabell.uber.space
[isabell@moondust ~]$ php occ config:system:set overwrite.cli.url --value="https://${USER}.uber.space"
System config value overwrite.cli.url set to string https://isabell.uber.space

Logs¶

Create symlinks to the log files for easier access:

[isabell@moondust ~]$ ln --symbolic ~/nextcloud_data/nextcloud.log ~/logs/nextcloud.log
[isabell@moondust ~]$ ln --symbolic ~/nextcloud_data/updater.log ~/logs/nextcloud-updater.log

You can now log in to your Nextcloud using the domain you configured. Before using it in production, continue with the sections below to enable email, optimize performance, and set up background jobs.

Configure email¶

Go to settings > Administration > Basic settings and configure the email-server.

Background jobs¶

For the server to work properly, it's important to configure background jobs correctly. Cron is the recommended setting.

Add the following cronjob to your crontab:

*/5  *  *  *  * sleep $(( 1 + RANDOM \% 60 )) ; php -f /var/www/virtual/$USER/html/cron.php > $HOME/logs/nextcloud-cron.log 2>&1

The actual cronjob is preceded by a random sleep of maximum one minute to prevent load peaks every 5 minutes due to simultaneous execution of all cronjobs. The \% is required as crontab replaces % with new-line characters.

Configure Nextcloud to rely on the configured cronjob:

[isabell@moondust ~]$ php occ background:cron
Set mode for background jobs to 'cron'

APCu caching¶

To enable APCu memory caching, run:

[isabell@moondust ~]$ php occ config:system:set memcache.local --value='\OC\Memcache\APCu'
System config value memcache.local set to string \OC\Memcache\APCu

URL rewriting¶

If you prefer cleaner URLs without index.php, run the following commands:

[isabell@moondust ~]$ php occ config:system:set htaccess.RewriteBase --value='/'
System config value htaccess.RewriteBase set to string /
[isabell@moondust ~]$ php occ maintenance:update:htaccess
.htaccess has been updated

Database maintenance¶

To optimize the database configuration, run these commands:

[isabell@moondust ~]$ cd html
[isabell@moondust html]$ php occ db:add-missing-indices --no-interaction
[isabell@moondust html]$ php occ db:add-missing-columns --no-interaction
[isabell@moondust html]$ php occ db:add-missing-primary-keys --no-interaction
[isabell@moondust html]$ php occ db:convert-filecache-bigint --no-interaction

Tuning¶

Redis Caching¶

To improve performance, set up Redis as a distributed memory cache for file locking and distributed caching. APCu remains configured as the local memory cache.

First, create the Redis configuration. Create the file ~/.redis/conf with the following content — replace <user> with your Uberspace username:

unixsocket /home/<user>/.redis/sock
daemonize no
port 0
save ""

[isabell@moondust ~]$ mkdir ~/.redis

Then set up the Redis service:

[isabell@moondust ~]$ uberspace service add redis "redis-server /home/${USER}/.redis/conf" --workdir /home/${USER}/.redis/

Configure Nextcloud to use Redis:

[isabell@moondust ~]$ php occ config:system:set redis host --value='/home/'"${USER}"'/.redis/sock'
[isabell@moondust ~]$ php occ config:system:set redis port --value=0 --type=integer
[isabell@moondust ~]$ php occ config:system:set memcache.distributed --value='\OC\Memcache\Redis'
[isabell@moondust ~]$ php occ config:system:set memcache.locking --value='\OC\Memcache\Redis'

Strict Transport Security¶

For improved security, enable HTTP Strict Transport Security to instruct browsers to only connect via HTTPS:

[isabell@moondust ~]$ uberspace web header add / Strict-Transport-Security "max-age=31536000"

Client Push (notify_push)¶

notify_push enables instant push notifications to Nextcloud clients, replacing the slower polling mechanism. This reduces delay for new messages, calendar events, and file changes.

Install the notify_push app:

[isabell@moondust ~]$ php occ app:install notify_push

Download the notify_push binary and place it in your ~/bin/ directory:

[isabell@moondust ~]$ curl -L -o ~/bin/notify_push "https://github.com/nextcloud/notify_push/releases/latest/download/notify_push-x86_64-unknown-linux-musl"
[isabell@moondust ~]$ chmod +x ~/bin/notify_push

Set up a web backend for the push server:

[isabell@moondust ~]$ uberspace web backend add /push PORT 7820 --remove-prefix --force --wait

On Uberspace 8, the Caddy reverse proxy overwrites the X-Forwarded-For header, which causes notify_push's trusted proxy self-test to fail. To work around this, run a local PHP built-in server that notify_push can connect to directly, bypassing Caddy:

Create the router script. Create the file ~/nc-local/router.php with the following content — replace $USER with your Uberspace username:

<?php
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$staticFile = '/var/www/virtual/$USER/html' . $path;
if ($path && $path !== '/' && file_exists($staticFile) && !is_dir($staticFile) && php_sapi_name() === 'cli-server') {
    return false;
}
$_SERVER['SCRIPT_NAME'] = '/index.php';
$_SERVER['SCRIPT_FILENAME'] = '/var/www/virtual/$USER/html/index.php';
chdir('/var/www/virtual/$USER/html');
require '/var/www/virtual/$USER/html/index.php';

[isabell@moondust ~]$ mkdir ~/nc-local

Start the local PHP server as a service:

[isabell@moondust ~]$ uberspace service add nc-local "php -S 127.0.0.1:7997 $HOME/nc-local/router.php" --workdir /var/www/virtual/$USER/html

Now create the notify_push service:

[isabell@moondust ~]$ uberspace service add notify_push "$HOME/bin/notify_push /var/www/virtual/${USER}/html/config/config.php --port 7820" --workdir /var/www/virtual/$USER/html

Configure the service to use the local PHP server instead of the public URL, so notify_push can reach Nextcloud without going through Caddy. Create the file ~/.config/systemd/user/notify_push.service.d/override.conf with the following content:

[Service]
Environment=NEXTCLOUD_URL=http://127.0.0.1:7997

[isabell@moondust ~]$ mkdir -p ~/.config/systemd/user/notify_push.service.d

Reload systemd and restart notify_push:

[isabell@moondust ~]$ systemctl --user daemon-reload
[isabell@moondust ~]$ systemctl --user restart notify_push

Configure Nextcloud to trust the push server and register the endpoint:

[isabell@moondust ~]$ php occ config:system:set trusted_proxies 0 --value=127.0.0.1
[isabell@moondust ~]$ php occ config:system:set notify_push_endpoint --value="https://${USER}.uber.space/push"

Run the self-test to verify everything works:

[isabell@moondust ~]$ php occ notify_push:self-test

All checks should pass:

✓ redis is configured
✓ push server is receiving redis messages
✓ push server can load mount info from database
✓ push server can connect to the Nextcloud server
✓ push server is a trusted proxy
✓ push server is running the same version as the app

Updates¶

Check the changelog regularly or subscribe to the project’s Github release feed with your favorite feed reader to stay informed about new updates and releases.

The easiest way to update Nextcloud is to use the web updater provided in the admin section of the Web Interface. You can also update via the command line, to do so create ~/bin/nextcloud-update with the following content:

#!/usr/bin/env bash
## Updater automatically works in maintenance:mode.
## Use the Uberspace backup system for files and database if you need to roll back.
## The Nextcloud updater creates backups only to safe base and app code data and config files
## so it takes ressources you might need for your productive data.
## Deactivate NC-updater Backups with --no-backup

set -euo pipefail

# Identifier for the journal logs
JOURNAL_TAG="nextcloud-update"

# Use echo and pipe to logger to avoid issues with messages starting with hyphens
echo "--- $(date '+%F %T') --- Starting Nextcloud update script" | logger -t "$JOURNAL_TAG"

run() {
  local tmp_log
  tmp_log=$(mktemp)

  # Execute the command
  # 2>&1  -> Redirect stderr to stdout
  # tee   -> Save real-time output to the temp file
  # logger -> Stream real-time output to the systemd journal
  if ! "$@" 2>&1 | tee "$tmp_log" | logger -t "$JOURNAL_TAG"; then
    echo "FEHLER bei: $*"
    echo
    cat "$tmp_log"
    rm -f "$tmp_log"
    exit 1
  fi

  rm -f "$tmp_log"
}

cd "/var/www/virtual/$USER/html/"

run php updater/updater.phar -vv --no-backup --no-interaction

## database optimisations
run php occ db:add-missing-primary-keys --no-interaction
run php occ db:add-missing-columns --no-interaction
run php occ db:add-missing-indices --no-interaction
run php occ db:convert-filecache-bigint --no-interaction

run php occ app:update --all
## App updates may require additional steps to be done by the `upgrade` command
run php occ upgrade

echo "--- Nextcloud update script finished successfully ---" | logger -t "$JOURNAL_TAG"
exit 0

Make the script executable:

[isabell@moondust ~]$ chmod +x ~/bin/nextcloud-update

To check for updates daily add another cronjob.

@daily $HOME/bin/nextcloud-update

Tip

Use journalctl --user --unit nextcloud-update to read the logs of the script.