Skip to content

Architecture

Gibran Khan edited this page Nov 18, 2026 · 1 revision

Architecture

The default is Nextcloud 35.

Each instance has its own Nextcloud jail, application datasets and private network. Office and Talk services are added only when selected. The FreeBSD host manages ZFS, routing, PF and startup; application services run inside jails or a VM.

What runs where

Using cloud as the example instance name:

Component Location Services
Nextcloud — always cloudnc jail Apache, PHP-FPM, Nextcloud, MariaDB, Redis and Client Push
ONLYOFFICE — default office choice cloudoo jail Native Document Server and its nginx frontend
Euro-Office — alternative cloudoffice VM Alpine Linux with Euro-Office in Docker
Collabora CODE — alternative cloudoffice VM Alpine Linux with CODE in Docker
Talk — optional with any office choice cloudtk jail Signaling, NATS, Janus and coturn

Choose one office backend or none. No office means no office jail, VM or office datasets. Talk remains available independently.

Jails are thick VNET jails managed by Bastille: each has its own FreeBSD userland and network stack, but shares the host kernel. Office VMs run their own Linux kernel under bhyve, managed through vm-bhyve. Docker runs inside those VMs, not on the FreeBSD host.

ZFS layout

The installer uses an existing ZFS pool. After plan approval, it creates owned datasets for the selected services; it does not repartition your disks.

POOL/cloud-installer/
├── bastille/                 Shared Bastille storage
│   ├── releases/             FreeBSD releases
│   └── jails/JAIL/root       Each jail's operating-system root
├── vm/                       Shared VM-manager storage, when needed
└── instances/NAME/           One instance's application datasets

The matching host paths start at /srv/cloud-installer. For example, POOL/cloud-installer/instances/cloud/nc-data is mounted at /srv/cloud-installer/instances/cloud/nc-data.

Under each instances/NAME:

Dataset Purpose Created for
nc-app Nextcloud code, apps and configuration Every instance
nc-data Nextcloud user files Every instance
nc-database MariaDB database files Every instance
nc-logs, nc-db-logs Jail and database logs Every instance
nc-tmp Nextcloud temporary files Every instance
office-runtime, office-data, office-logs Document Server runtime data, working data and logs Native ONLYOFFICE
office-vm Office VM disk and configuration Euro-Office or CODE
talk-runtime, talk-logs Talk service state and logs Selected Talk

These are separate sibling datasets, not directories inside the jail root. For jails, Bastille mounts them read/write using nullfs before application setup—for example, nc-data becomes /var/nc-data and nc-database becomes /var/db/mysql inside the Nextcloud jail.

Datasets use LZ4 compression and disable access-time updates. The database dataset uses a 16 KiB record size. No installer quota is imposed by default; optional caps limit usage but do not reserve free space.

Office VM storage

Each VM-backed instance has one guest disk:

/srv/cloud-installer/instances/NAME/office-vm/NAMEoffice/disk0.img

This is a raw disk file on ZFS, not a zvol. The downloaded Alpine QCOW2 source image is converted into the running raw disk. The guest OS, Docker and its persistent office storage live inside this disk; they do not use the native ONLYOFFICE datasets. Saved documents remain in Nextcloud.

Networking

  • Nextcloud, the selected office runtime and optional Talk each have a separate private bridge and /30 IPv4 segment. The physical uplink is not bridged in.
  • The host routes and filters traffic through PF, allowing the required frontend, callback and outbound connections while isolating other instances.
  • Web traffic reaches Apache in the Nextcloud jail, which proxies selected office and Talk web endpoints. Talk media/TURN uses its separately configured ports.
  • HTTPS terminates in the Nextcloud jail or at your external reverse proxy.

Existing jails can coexist when the host meets the host preparation requirements.

State and removal

Private installer configuration and phase records live separately under /var/db/cloud-installer/instances/NAME. Keep the original installer for Resume, recovery and removal.

Normal removal deletes jail roots and withdraws VM registration/networking, but retains application datasets and their snapshots, including office VM disks. Jail-root settings are separate, so retained data is not a complete system backup or an automatic reinstallation. See Uninstall for retention and explicit data purge.

Clone this wiki locally