Nextcloud AIO

Purpose

Nextcloud AIO provides private file storage, synchronization, sharing, productivity, and collaboration services for the Bytek environment.

Nextcloud currently supports or is intended to support:

Nextcloud runs as an isolated application VM and uses Nextcloud All-in-One to manage its containers.

Service Information

User application:

Open Nextcloud

AIO management address:

https://192.168.2.100:8080/

Architecture Role

Nextcloud is the central user-file and collaboration platform.

Nextcloud is separate from:

This separation limits the effect of an application failure and allows Nextcloud storage to grow independently from the infrastructure VMs.

Container Architecture

Nextcloud AIO manages the application stack.

Core containers include equivalents of:

Optional containers may include:

Optional containers should be added one at a time and tested before enabling another.

Public Request Flow

When an external user opens Nextcloud:

Internal Request Flow

When a LAN user opens Nextcloud:

Internal clients use the same HTTPS hostname as external clients.

Traefik Route

The Nextcloud Traefik router uses:

Do not attach Authentik ForwardAuth to the Nextcloud Traefik router.

Nextcloud requires direct access for:

Nextcloud performs user authentication through its native OIDC integration.

AIO Management Interface

The AIO management interface is available only by private IP:

https://192.168.2.100:8080/

The management interface uses its own certificate, so a browser warning may appear.

Always use the private IP for AIO management.

Do not use:

The AIO management interface controls:

Restricted Ports

The following ports must not be exposed publicly:

Only Traefik should reach TCP port 11000 during normal operation.

LAN administrators may reach TCP port 8080.

Storage Architecture

Nextcloud uses separate virtual disks for the operating system and user data.

Operating-System Disk

User-Data Disk

The operating-system disk appeared as /dev/sdb, while the 500 GB data disk appeared as /dev/sda during initial configuration.

Linux device names may change, so the permanent mount uses the filesystem UUID rather than /dev/sda1.

Data-Disk Validation

Confirm the data disk is mounted using:

findmnt /mnt/nextcloud-data

Confirm available capacity using:

df -h / /mnt/nextcloud-data

Confirm the filesystem using:

lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINTS

Confirm the data directory exists using:

sudo ls -ld /mnt/nextcloud-data/ncdata

The Nextcloud containers should not be started if the expected data filesystem is missing.

Starting the application with an unmounted data path could cause data to be written to the operating-system disk instead.

Filesystem Mount

The data filesystem is mounted through /etc/fstab using its UUID.

The mount point is:

/mnt/nextcloud-data

The intended behavior is:

Review the mount after every storage or boot issue.

AIO Data Directory

The AIO deployment uses:

The directory should remain on the 500 GB user-data disk.

Do not move the directory manually while Nextcloud containers are running.

Do not directly edit files inside the Nextcloud data directory using normal filesystem tools unless following a documented recovery process.

Nextcloud tracks files through its database and filesystem metadata.

Files manually copied into the data directory may not appear correctly until an application-level rescan is performed.

Authentication

Nextcloud uses native OpenID Connect through Authentik.

The installed Nextcloud application is:

Do not install another OIDC login application alongside it unless a migration is deliberately planned.

Avoid enabling overlapping authentication applications such as:

The OIDC Identity Provider application serves the opposite role by making Nextcloud an identity provider.

Authentik OIDC Configuration

Normal users must:

Do not attach bytek-admin as another required ALL binding for normal Nextcloud access.

Administrators who need Nextcloud should also belong to bytek-users.

Nextcloud OIDC Settings

The OIDC discovery endpoint must be reachable from inside the Nextcloud application container.

The client ID and client secret must match the Authentik Nextcloud provider.

Do not place the client secret in BookStack.

OIDC Login Flow

Nextcloud application permissions remain controlled inside Nextcloud.

Local Break-Glass Administrator

The local Nextcloud administrator must remain available.

The local account provides recovery when:

The direct local-login path is:

Open the Nextcloud Local Login

The local administrator password must:

A local Nextcloud second factor may be enabled for the break-glass account if recovery codes are stored securely.

Trusted Proxy

Nextcloud must trust Traefik as its reverse proxy.

Expected trusted proxy:

Review using:

sudo docker exec --user www-data nextcloud-aio-nextcloud php occ config:system:get trusted_proxies

The output should include Traefik’s current private address.

If Traefik’s IP changes, update:

HTTPS Detection

Nextcloud must generate HTTPS URLs when accessed through Traefik.

If Nextcloud generates HTTP links, investigate:

The expected external URL is:

https://cloud.bytek.ca

Do not set the external URL to the private IP or TCP port 11000.

Office Integration

Nextcloud uses the AIO-managed Collabora Online container.

This component provides browser-based document editing and simultaneous collaboration.

The Nextcloud Office application connects Nextcloud to the AIO-managed Collabora CODE server.

Do not also install the separate Built-in CODE Server application.

Using both would create competing office backends and complicate troubleshooting.

Office Dictionaries

Configured dictionaries:

These provide:

Canadian French would normally use fr_CA, but the AIO interface should be checked before adding a locale not listed as supported.

Locale values are separated by spaces.

Office Validation

To validate collaborative editing:

If a document does not open:

Enabled Applications

Recommended core applications include:

Applications that may be added later include:

Add applications only when there is a clear use case.

Every additional application becomes part of:

Team Folders

Team Folders may be used for administrator-managed shared storage.

Use Team Folders instead of placing every shared resource inside one user’s personal files.

Possible shared folders include:

Team Folder permissions should use stable Nextcloud users and groups after OIDC account provisioning has been tested.

Optional AIO Containers

Collabora

Enabled for browser-based document editing.

Imaginary

May be enabled later for expanded preview support.

Possible preview formats include:

Review compatibility before enabling server-side encryption.

ClamAV

May be enabled later for antivirus scanning.

ClamAV requires additional memory and may affect upload processing.

Full-Text Search

May be enabled later when enough content exists to justify indexing.

Initial indexing can consume significant resources and affect availability.

Nextcloud Talk

May be enabled later.

Talk requires deliberate network configuration, including TCP and UDP port 3478 for TURN functionality.

Do not enable Talk before designing the complete VPS, WireGuard, firewall, and guest-port path.

HaRP

May be enabled if a future ExApp requires it.

Do not enable it without a specific application requirement.

Docker Socket Proxy

Do not enable the deprecated Docker Socket Proxy when HaRP is the supported alternative for the intended application.

Community Containers

AIO Community Containers are not official core Nextcloud containers.

Community containers may:

Do not enable community containers merely because they are available.

Plex was considered as an AIO Community Container but rejected in favor of a dedicated Plex VM.

Reasons include:

Time Zone

Nextcloud AIO uses:

The Debian host should also use:

Verify the host using:

timedatectl

Expected properties:

The AIO time-zone setting and Debian host time zone are separate settings.

Email Configuration

Nextcloud should use SMTP for:

WHC SMTP settings should be obtained from:

Typical secure combinations include:

The full mailbox address is normally used as the SMTP username.

Use the mailbox password, not the cPanel password.

Do not store the SMTP password in BookStack.

Email Troubleshooting

If Nextcloud cannot send email:

If no attempt appears in cPanel Track Delivery, the message may not have reached the WHC mail server.

Application Administration Overview

Review the Nextcloud administration overview after installation and updates.

Common warnings may include:

Use the exact warning text from the installed Nextcloud version before running administrative commands.

Do not copy commands from unrelated versions without reviewing the current warning.

Default Phone Region

For Canadian phone numbers, use:

This helps Nextcloud interpret local phone-number formats.

Review the current value using the Nextcloud system configuration.

Container Management

Nextcloud AIO containers should be managed through the AIO interface whenever practical.

AIO management address:

https://192.168.2.100:8080/

Use the AIO interface for:

Do not manually recreate AIO-generated application containers unless following an AIO-specific recovery procedure.

Docker Compose Management

The master container deployment is stored under:

/opt/nextcloud-aio

Move to the directory using:

cd /opt/nextcloud-aio

Validate Compose using:

sudo docker compose config --quiet

Check the master container using:

sudo docker compose ps

View master-container logs using:

sudo docker logs nextcloud-aio-mastercontainer --tail 100

Container-level settings in the master Compose definition require recreation of the master container.

AIO-managed child containers remain controlled through AIO.

Container Health

List containers using:

sudo docker ps --format='table {{.Names}}\t{{.Status}}\t{{.Ports}}'

Expected core containers include equivalents of:

A running container may still be unhealthy.

Review the status and relevant application endpoint.

Backend Validation

Confirm TCP port 11000 from the Nextcloud VM using:

curl -I http://127.0.0.1:11000/

Confirm from the Traefik VM using:

curl -I http://192.168.2.100:11000/

A redirect or Nextcloud response confirms the HTTP backend is reachable.

A timeout indicates a firewall or routing issue.

A connection refusal indicates that the VM was reached but no service is listening.

Public Validation

Validate the public hostname using:

Open Nextcloud

Expected behavior:

A browser cache previously caused a Firefox TLS error while Edge worked.

Before changing Traefik or certificates, test:

Monitoring

Recommended Uptime Kuma monitors include:

Expected routed status:

The Nextcloud VM firewall must allow Uptime Kuma if direct monitoring is used.

Firewall Policy

AIO Management

Allow TCP port 8080 only from approved LAN or VPN management sources.

AIO Apache Backend

Allow TCP port 11000 from:

SSH

Allow SSH only from approved LAN or VPN administration sources.

Public Exposure

Do not publicly forward:

Backup Architecture

The AIO Borg backup location is currently not configured.

This is intentional because the currently available local destinations are not sufficiently separate from the live data or existing Proxmox backup.

Current backup protection consists of:

An AIO Borg repository placed on the same Nextcloud data disk would not protect against failure of that disk.

It would also cause the Proxmox backup to contain both live data and an embedded Borg backup copy.

Future AIO Backup

A future AIO Borg repository should use:

A remote AIO backup would add an application-aware recovery method alongside Proxmox’s whole-VM backup.

The separate location is more important than simply enabling the backup field.

Proxmox Backup Coverage

Both Nextcloud virtual disks must be included in the Proxmox backup.

Review the VM configuration using:

qm config <NEXTCLOUD_VMID>

Confirm the operating-system disk and data disk do not contain:

The initial consistent baseline may use a stopped backup.

Routine backups may use snapshot mode if brief application downtime is undesirable.

Restore Testing

A Nextcloud restore test must avoid creating a duplicate live instance.

Recommended procedure:

Do not connect the restored clone to the production LAN while the live Nextcloud VM is active.

Data Growth

Monitor Nextcloud growth using:

df -h /mnt/nextcloud-data

Review directory usage using:

sudo du -sh /mnt/nextcloud-data/ncdata

Monitor the Proxmox user-data thin pool using:

pvesm status

Also review LVM-thin data and metadata utilization.

Storage monitoring must account for:

Security Considerations

Common Failure Scenarios

AIO Management Loads but Nextcloud Does Not

Check:

Direct Backend Works but Public Hostname Fails

Check:

Public Hostname Works but OIDC Fails

Check:

Discovery Endpoint Not Reachable

Check DNS inside the Nextcloud container.

Use:

sudo docker exec nextcloud-aio-nextcloud getent hosts portal.bytek.ca

No output indicates container DNS failure.

After confirming Pi-hole, restart the AIO containers or Docker as appropriate.

User Is Denied by Authentik

Check the Nextcloud Authentik application bindings.

Expected requirements:

Do not require bytek-admin for all Nextcloud users.

Wrong Time Display

Confirm:

Data Disk Missing

Do not start normal application use until the data disk is mounted.

Check:

Power-Failure Recovery

After a power interruption:

If container DNS remains broken after Pi-hole recovery, restart the affected containers in a controlled manner.

Recovery Procedure

If the Nextcloud application is unavailable:

If the data disk is damaged:

Validation Checklist

Document Control