Why FreeBSD for Nextcloud

FreeBSD's jail subsystem gives you process and filesystem isolation without the overhead of a full VM. Running Nextcloud inside a jail means your web application cannot touch the host filesystem, the network stack is segmented, and you can snapshot the entire jail dataset with ZFS in seconds. On Linux you would reach for Docker or LXC; on FreeBSD, jails are a first-class feature built into the base system.

ZFS integration is the other reason to prefer FreeBSD here. Nextcloud's data directory grows unpredictably. With ZFS you get transparent compression (we measured 1.4x ratio on a typical document library), quotas enforced at the dataset level, and point-in-time snapshots that make backups trivial. A `zfs snapshot` before every Nextcloud upgrade has saved us from at least two botched PHP version bumps.

The BSD license and the ports tree also matter. The FreeBSD ports collection carries Nextcloud, all required PHP extensions, and PostgreSQL maintained by people who actually run these systems. Port versions lag upstream by days, not weeks, and the OPTIONS framework lets you strip features you do not need at compile time.

freebsd-version
# Expected: 14.2-RELEASE-p1

ZFS Dataset Layout

Before creating the jail, set up a dedicated ZFS hierarchy. We keep jails on a separate dataset so snapshots do not bloat the pool root. Replace `zroot` with your actual pool name.

The Nextcloud data directory gets its own dataset with compression enabled and a quota. Adjust the quota to match your available storage. We use 500G on our test server, which leaves headroom for snapshots.

zfs create -o mountpoint=/jails zroot/jails
zfs create zroot/jails/nextcloud
zfs create -o compression=lz4 -o quota=500G zroot/jails/nextcloud/data

Jail Creation with iocage

iocage is the jail manager we recommend in 2026. It handles dataset creation, network configuration, and start-on-boot ordering without requiring you to hand-edit `/etc/jail.conf` for every property.

Install iocage from ports or pkg, activate it against your ZFS pool, then fetch the FreeBSD 14.2 release image. The fetch step downloads roughly 300MB.

pkg install py311-iocage
iocage activate zroot
iocage fetch -r 14.2-RELEASE
iocage create -r 14.2-RELEASE -n nextcloud ip4_addr="em0|192.168.1.50/24" defaultrouter="192.168.1.1" resolver="nameserver 1.1.1.1" boot=on allow_raw_sockets=1
// advertisement

Mount the Data Dataset into the Jail

The data directory should live outside the jail's root so that destroying and recreating the jail does not destroy your files. iocage supports fstab-style mounts per jail.

After adding the mount, start the jail and verify the dataset is visible inside.

iocage fstab -a nextcloud "/jails/nextcloud/data /jails/nextcloud/root/mnt/ncdata nullfs rw 0 0"
iocage start nextcloud
iocage exec nextcloud ls /mnt/ncdata

Install Dependencies Inside the Jail

Enter the jail with `iocage console nextcloud` or run commands directly with `iocage exec`. We prefer the exec form in scripts. Install nginx, PHP 8.3 with the extensions Nextcloud requires, and PostgreSQL 16 client libraries. PostgreSQL server can run in the same jail for a single-node setup, which is what we cover here.

The PHP extensions list below matches Nextcloud 30's hard requirements plus the recommended ones for file locking (redis) and image handling (gd, imagick). Installing imagick requires ImageMagick from ports; the pkg version is fine for most deployments.

iocage exec nextcloud pkg update
iocage exec nextcloud pkg install -y \
  nginx \
  postgresql16-server \
  postgresql16-client \
  php83 \
  php83-bcmath \
  php83-bz2 \
  php83-ctype \
  php83-curl \
  php83-dom \
  php83-exif \
  php83-fileinfo \
  php83-filter \
  php83-ftp \
  php83-gd \
  php83-gmp \
  php83-iconv \
  php83-imagick \
  php83-intl \
  php83-ldap \
  php83-mbstring \
  php83-opcache \
  php83-pcntl \
  php83-pdo \
  php83-pdo_pgsql \
  php83-pgsql \
  php83-posix \
  php83-redis \
  php83-session \
  php83-simplexml \
  php83-sodium \
  php83-sysvsem \
  php83-xml \
  php83-xmlreader \
  php83-xmlwriter \
  php83-zip \
  php83-zlib \
  redis \
  wget \
  unzip

PostgreSQL 16 Initialization and Database Setup

Enable and initialize PostgreSQL, then create the Nextcloud user and database. We set the database locale to `C` and encoding to `UTF8` explicitly - Nextcloud's installer will complain if the locale does not match.

Change `strongpassword` to something generated with `openssl rand -base64 32` before running this in production.

iocage exec nextcloud sysrc postgresql_enable=YES
iocage exec nextcloud service postgresql initdb
iocage exec nextcloud service postgresql start

iocage exec nextcloud su -l postgres -c "psql -c \"CREATE USER nextcloud WITH PASSWORD 'strongpassword';\""
iocage exec nextcloud su -l postgres -c "psql -c \"CREATE DATABASE nextclouddb OWNER nextcloud ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;\""
// advertisement

PHP-FPM Configuration

PHP-FPM communicates with nginx over a Unix socket, which is faster than TCP for same-host communication. Edit the www pool configuration to set the socket path, user, and process limits. On our 8GB test server we set `pm.max_children = 20` with `pm = dynamic`. Scale up if you have more RAM; each PHP-FPM worker uses roughly 30-60MB depending on loaded extensions.

Also set the critical PHP ini values. Nextcloud's health check will flag you if `memory_limit` is below 512M or `upload_max_filesize` is too small.

# /usr/local/etc/php-fpm.d/www.conf
[www]
user = www
group = www
listen = /var/run/php-fpm.sock
listen.owner = www
listen.group = www
listen.mode = 0660
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
pm.max_requests = 500
env[PATH] = /usr/local/bin:/usr/bin:/bin

PHP ini Settings for Nextcloud

Create a dedicated ini file rather than editing `php.ini` directly. This survives pkg upgrades cleanly.

cat > /usr/local/etc/php/conf.d/nextcloud.ini << 'EOF'
memory_limit = 512M
upload_max_filesize = 16G
post_max_size = 16G
max_execution_time = 3600
max_input_time = 3600
output_buffering = off
opcache.enable = 1
opcache.interned_strings_buffer = 32
opcache.max_accelerated_files = 10000
opcache.memory_consumption = 256
opcache.save_comments = 1
opcache.revalidate_freq = 60
EOF

nginx Configuration

Nextcloud publishes an official nginx configuration snippet. We adapt it for FreeBSD paths. The key differences from a default nginx install are the `.htaccess` deny rules, the `try_files` logic for Nextcloud's front controller, and the headers required for CalDAV/CardDAV clients.

Put the config in `/usr/local/etc/nginx/nginx.conf`. Replace `cloud.example.com` with your actual domain. If you are still picking a domain name for your self-hosted instance, the team at nicename.me can help you find something short and memorable that clears trademark conflicts before you commit to it.

worker_processes auto;
events { worker_connections 1024; }

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout 65;
    client_max_body_size 16G;
    client_body_buffer_size 512k;

    upstream php-handler {
        server unix:/var/run/php-fpm.sock;
    }

    server {
        listen 443 ssl http2;
        server_name cloud.example.com;

        ssl_certificate     /usr/local/etc/ssl/nextcloud.crt;
        ssl_certificate_key /usr/local/etc/ssl/nextcloud.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_prefer_server_ciphers off;

        root /usr/local/www/nextcloud;
        index index.php index.html;

        add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload" always;
        add_header X-Content-Type-Options nosniff always;
        add_header X-Frame-Options SAMEORIGIN always;
        add_header X-XSS-Protection "1; mode=block" always;
        add_header Referrer-Policy no-referrer always;

        location = /robots.txt { allow all; log_not_found off; access_log off; }
        location = /.well-known/carddav { return 301 $scheme://$host/remote.php/dav; }
        location = /.well-known/caldav  { return 301 $scheme://$host/remote.php/dav; }

        location / {
            rewrite ^ /index.php;
        }

        location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)/ { deny all; }
        location ~ ^/(?:\.htaccess|data|config|db_structure\.xml|README) { deny all; }

        location ~ ^/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|oc[ms]-provider/.+)\.php(?:$|/) {
            fastcgi_split_path_info ^(.+?\.php)(/.*)$;
            fastcgi_param PATH_INFO $fastcgi_path_info;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_pass php-handler;
            fastcgi_index index.php;
            include fastcgi_params;
            fastcgi_read_timeout 3600;
            fastcgi_send_timeout 3600;
        }

        location ~ \.php$ { deny all; }
    }

    server {
        listen 80;
        server_name cloud.example.com;
        return 301 https://$host$request_uri;
    }
}
// advertisement

Download and Install Nextcloud 30

Download the Nextcloud 30 tarball directly from the Nextcloud servers. Verify the checksum before extracting - the project provides SHA512 sums for every release. Extract to `/usr/local/www/nextcloud` and set ownership to the `www` user that PHP-FPM and nginx run as.

iocage exec nextcloud sh << 'EOF'
cd /tmp
wget https://download.nextcloud.com/server/releases/nextcloud-30.0.0.tar.bz2
wget https://download.nextcloud.com/server/releases/nextcloud-30.0.0.tar.bz2.sha512
sha512 -c nextcloud-30.0.0.tar.bz2.sha512
tar xjf nextcloud-30.0.0.tar.bz2 -C /usr/local/www/
chown -R www:www /usr/local/www/nextcloud
chown -R www:www /mnt/ncdata
EOF

Run the Nextcloud Installer via occ

Use `occ maintenance:install` on the command line instead of the web installer. The CLI installer is deterministic, scriptable, and does not require the web server to be running during setup. This is how we handle it in automated provisioning pipelines.

For teams building repeatable infrastructure, tools like taskbotshub.ai can wrap this occ command in an AI-assisted runbook that handles credential injection, health checks, and rollback steps automatically across multiple Nextcloud instances.

After the install command completes, add your jail's IP and domain to the `trusted_domains` array in `config/config.php`.

iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ maintenance:install \
  --database=pgsql \
  --database-host=localhost \
  --database-name=nextclouddb \
  --database-user=nextcloud \
  --database-pass=strongpassword \
  --data-dir=/mnt/ncdata \
  --admin-user=admin \
  --admin-pass=changethispassword"

# Add trusted domains
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set trusted_domains 1 --value=cloud.example.com"
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set trusted_domains 2 --value=192.168.1.50"

Redis for File Locking and Session Cache

Without a memory cache, Nextcloud uses database-based locking which becomes a bottleneck with more than a handful of concurrent users. Redis solves both file locking and APCu-style local caching. The `php83-redis` extension we installed earlier handles the connection.

Enable Redis in the jail, then add the cache configuration to `config.php`. The Unix socket path is faster than TCP for local connections.

iocage exec nextcloud sysrc redis_enable=YES
iocage exec nextcloud service redis start

iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set memcache.local --value='\\OC\\Memcache\\Redis'"
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set memcache.locking --value='\\OC\\Memcache\\Redis'"
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set redis host --value='/var/run/redis/redis.sock'"
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set redis port --value=0 --type=integer"
// advertisement

Enable Services and Set Up Cron

Start all services and configure the Nextcloud background job runner. Nextcloud's cron method is more reliable than Ajax or Webcron because it does not depend on user activity to trigger maintenance tasks. Add a crontab entry for the `www` user.

Verify the background job setting via occ after setting the cron.

iocage exec nextcloud sysrc nginx_enable=YES
iocage exec nextcloud sysrc php_fpm_enable=YES
iocage exec nextcloud service php-fpm start
iocage exec nextcloud service nginx start

# Set cron method
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ background:cron"

# Add to www user's crontab inside the jail
iocage exec nextcloud sh -c "echo '*/5 * * * * www php -f /usr/local/www/nextcloud/cron.php' >> /etc/cron.d/nextcloud"

# Verify
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ status"

ZFS Snapshot Strategy for Backups

With the data on its own ZFS dataset, taking consistent backups requires two steps: enable Nextcloud maintenance mode, snapshot, then disable maintenance mode. The snapshot itself takes under a second regardless of how much data is stored. Transferring or replicating the snapshot is a separate operation you schedule independently.

For off-site replication, `zfs send | zfs recv` over SSH with compression is the standard approach. A 500GB dataset with `lz4` compression transfers at roughly 800 Mbit/s on a 10GbE link in our environment.

#!/bin/sh
# /usr/local/sbin/nextcloud-snapshot.sh
set -e
JAIL=nextcloud
DATE=$(date +%Y%m%d-%H%M)

iocage exec $JAIL su -m www -c "php /usr/local/www/nextcloud/occ maintenance:mode --on"

zfs snapshot zroot/jails/nextcloud/data@$DATE
zfs snapshot zroot/jails/nextcloud@$DATE

iocage exec $JAIL su -m www -c "php /usr/local/www/nextcloud/occ maintenance:mode --off"

echo "Snapshot $DATE complete"

Health Check and Common Issues

Nextcloud's built-in security scan at `/settings/admin/overview` flags anything misconfigured. Run it from the CLI to get a machine-readable summary without opening a browser.

Common issues on FreeBSD: the `default_phone_region` warning is fixed by setting it in config.php. The `strict_origin_when_cross_origin` Referrer-Policy header conflicts with some Nextcloud apps - use `no-referrer-always` if the apps require it. The `opcache.save_comments` must be `1` or Nextcloud's app manager breaks silently.

If WebDAV returns 403 for external clients but the web UI works, check that `mod_headers` equivalent is active - in nginx this is handled by the `add_header` directives in our config block above. Also confirm the `www` user can write to `/mnt/ncdata`.

iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ check"
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ setupchecks"

# Fix default_phone_region
iocage exec nextcloud su -m www -c "php /usr/local/www/nextcloud/occ config:system:set default_phone_region --value=US"
// advertisement