From b2c1ba565f1481e9ae900a046a760f9345fb1806 Mon Sep 17 00:00:00 2001 From: gitea Date: Tue, 26 May 2026 21:47:21 +0100 Subject: [PATCH] Initial commit --- README.md | 330 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 330 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..13f41c5 --- /dev/null +++ b/README.md @@ -0,0 +1,330 @@ +# Nextcloud AIO — NFS Data Directory & Emergency Local Access + +A guide to moving Nextcloud AIO's data directory to an NFS share, maintaining file ownership integrity, and setting up an emergency local access VM for use during internet outages. + +--- + +## Overview + +This setup moves Nextcloud's primary data directory to an NFS share hosted on a local server (e.g. a NAS), with Nextcloud AIO running on a remote server (e.g. a Proxmox VM). This gives you: + +- Full Nextcloud functionality over the internet under normal conditions +- Direct local access to your data during internet outages +- A clean, single source of truth for all files + +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────┐ +│ Local Network (LAN) │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ Nextcloud AIO │ │ NAS / Local │ │ +│ │ (Proxmox VM) │◄───►│ Server (NFS) │ │ +│ │ │ NFS │ │ │ +│ └──────────────────┘ └──────────────────┘ │ +│ │ ▲ │ +│ │ Internet │ NFS (LAN) │ +│ ▼ │ │ +│ Remote Clients ┌──────────────┐ │ +│ (WebDAV / Desktop) │ Emergency VM │ │ +│ │ (Proxmox VM) │ │ +│ └──────────────┘ │ +└─────────────────────────────────────────────────┘ +``` + +--- + +## Part 1 — Moving the Nextcloud Data Directory to NFS + +### Why This Is Better Than External Storage + +Mounting the NFS share as Nextcloud's native `datadirectory` is cleaner than using Nextcloud's External Storage feature: + +| | Native Data Dir on NFS | External Storage | +|---|---|---| +| Nextcloud awareness | Transparent | Explicit backend | +| File ownership | Handled natively | Can have edge cases | +| Versioning & Trash | Fully supported | Can be quirky | +| Encryption | Works natively | Can have complications | +| Config complexity | One `config.php` change | Requires app setup | + +### NFS Mount Configuration + +Add to `/etc/fstab` on the Nextcloud server: + +``` +nas-server:/share /mnt/nextcloud nfs _netdev,auto 0 0 +``` + +The `_netdev` flag tells the OS to wait for the network before mounting — critical for a remote NFS share. + +### Key Considerations + +**File locking** — Use Redis for Nextcloud file locking rather than the database, as NFS can interfere with lock files: + +```php +// config.php +'memcache.locking' => '\OC\Memcache\Redis', +'redis' => [ + 'host' => 'localhost', + 'port' => 6379, +], +``` + +**UID/GID ownership** — Nextcloud's web server runs as `www-data` (typically UID 33 on Debian/Ubuntu). The NFS share must be accessible to this user. Check the UID with: + +```bash +id www-data +``` + +Configure your NFS server to export with matching UID permissions, and be cautious of NFS UID squashing settings (`no_root_squash` / UID mapping may be needed). + +--- + +## Part 2 — Emergency Local Access VM + +### Purpose + +A lightweight Linux VM running permanently on Proxmox, pre-configured to access the NFS share directly over the LAN. Used when internet access is unavailable but local file access is needed. + +### Why a Dedicated VM + +- Runs Linux, making UID/GID matching straightforward +- Accessible via SSH from any OS (Windows, Mac, Linux) +- No dependency on internet connectivity +- Keeps file ownership intact when writing to the NFS share + +### VM Setup Checklist + +1. Install a minimal Debian/Ubuntu server (no desktop environment required) +2. Set the local user's UID to match `www-data` on the Nextcloud server (UID 33): + ```bash + sudo usermod -u 33 your-username + ``` +3. Install required tools: + ```bash + sudo apt install nfs-common rsync mc tmux openssh-server + ``` +4. Add the NFS mount to `/etc/fstab`: + ``` + nas-server:/share /mnt/nextcloud nfs _netdev,auto 0 0 + ``` +5. Take a Proxmox snapshot of the VM once configured, so you can roll back if something goes wrong during an emergency file operation. + +--- + +## Part 3 — File Management Tools + +### Midnight Commander (mc) + +A terminal-based two-panel file manager, ideal for navigating and copying files over SSH without a GUI. + +```bash +sudo apt install mc +mc +``` + +#### Key Bindings + +| Key | Action | +|---|---| +| `Tab` | Switch between panels | +| `F3` | View file | +| `F4` | Edit file | +| `F5` | Copy | +| `F6` | Move | +| `F7` | New directory | +| `F8` | Delete | +| `F9` | Menu bar | +| `Insert` | Select/deselect files | +| `Ctrl+T` | Select by pattern (e.g. `*.jpg`) | +| `Alt+.` | Toggle hidden files | + +mc also has a built-in SFTP client (F9 → Left/Right → SFTP link), allowing you to browse a remote machine in one panel and the NFS mount in the other — all within a single SSH session. + +--- + +### tmux — Terminal Multiplexer + +tmux provides persistent terminal sessions and split-pane layouts, mimicking the two-panel feel of Midnight Commander while adding session resilience. + +#### Key Benefit +If your SSH connection drops during a large file transfer, the tmux session keeps running. Reconnect and reattach with: + +```bash +ssh user@emergency-vm +tmux attach -t emergency +``` + +#### Key Bindings + +| Key | Action | +|---|---| +| `Ctrl+b %` | Split vertically | +| `Ctrl+b "` | Split horizontally | +| `Ctrl+b ←→↑↓` | Move between panes | +| `Ctrl+b z` | Zoom current pane (toggle) | +| `Ctrl+b [` | Scroll mode | +| `Ctrl+b d` | Detach (session keeps running) | + +#### Emergency Session Startup Script + +Save as `~/emergency-session.sh` on the VM: + +```bash +#!/bin/bash +tmux new-session -d -s emergency -x 220 -y 50 + +# Left pane - staging area +tmux send-keys -t emergency 'cd /home/user/staging && ls -lah' Enter + +# Right pane - NFS mount +tmux split-window -h -t emergency +tmux send-keys -t emergency 'cd /mnt/nextcloud && ls -lah' Enter + +# Bottom pane - command input +tmux split-window -v -t emergency +tmux resize-pane -t emergency -y 10 +tmux send-keys -t emergency 'echo "Ready for commands"' Enter + +tmux attach -t emergency +``` + +```bash +chmod +x ~/emergency-session.sh +``` + +This creates the following layout: + +``` +┌──────────────────┬──────────────────┐ +│ ~/staging │ /mnt/nextcloud │ +│ │ │ +│ │ │ +├──────────────────┴──────────────────┤ +│ Command pane (rsync / scp) │ +└─────────────────────────────────────┘ +``` + +--- + +## Part 4 — Transferring Files with rsync + +### Recommended Flags + +```bash +rsync -avh --progress --stats +``` + +| Flag | Purpose | +|---|---| +| `-a` | Archive mode — preserves permissions, timestamps, symlinks | +| `-v` | Verbose output | +| `-h` | Human readable sizes | +| `--progress` | Per-file progress | +| `--stats` | Transfer summary | +| `--partial` | Keeps partial files if connection drops | +| `--append-verify` | Safely resumes interrupted transfers | + +### NFS Mount → Mac + +Mac has rsync and SSH built in. Enable Remote Login under System Settings → General → Sharing → Remote Login, then: + +```bash +# Push to Mac +rsync -avh --progress /mnt/nextcloud/username/files/ user@mac-ip:/Users/username/destination/ + +# Pull from Mac +rsync -avh --progress user@mac-ip:/Users/username/source/ /mnt/nextcloud/username/files/ +``` + +### NFS Mount → Windows + +Windows requires one of the following: + +**Option 1 — WSL2 (Recommended)** +WSL2 includes rsync and SSH. Windows drives are accessible at `/mnt/c/`, `/mnt/d/` etc. Start the SSH server in WSL2 first: +```bash +# In WSL2 +sudo service ssh start + +# From Emergency VM +rsync -avh --progress /mnt/nextcloud/username/files/ windowsuser@windows-ip:/mnt/c/Users/username/destination/ +``` + +**Option 2 — OpenSSH + scp** +OpenSSH Server is built into Windows 10/11 (Settings → Apps → Optional Features → OpenSSH Server): +```bash +scp -r /mnt/nextcloud/username/files/ windowsuser@windows-ip:"C:/Users/username/destination/" +``` + +**Option 3 — DeltaCopy** +A Windows application that wraps rsync as a Windows service — good for a set-and-forget solution without WSL2. + +--- + +## Part 5 — Resynchronising Nextcloud After an Outage + +Any files written directly to the NFS share (bypassing Nextcloud's API) will not be reflected in Nextcloud's database until a file scan is run. + +### Run a File Scan (Nextcloud AIO) + +```bash +# Scan all users +sudo docker exec -it --user www-data nextcloud-aio-nextcloud php occ files:scan --all + +# Scan a specific user +sudo docker exec -it --user www-data nextcloud-aio-nextcloud php occ files:scan username + +# Scan a specific path +sudo docker exec -it --user www-data nextcloud-aio-nextcloud php occ files:scan --path="/username/files" +``` + +Verify your container name first: +```bash +sudo docker ps --format "table {{.Names}}\t{{.Status}}" +``` + +### Automate the Scan on Internet Restoration + +Save as `/usr/local/bin/wait-and-scan.sh` on the Nextcloud server: + +```bash +#!/bin/bash +until ping -c1 8.8.8.8 &>/dev/null; do + sleep 30 +done +sudo docker exec --user www-data nextcloud-aio-nextcloud php occ files:scan --all +``` + +```bash +chmod +x /usr/local/bin/wait-and-scan.sh +``` + +Run via cron or a systemd service to trigger automatically when connectivity is restored. + +--- + +## Normal Operation vs Internet Outage — Summary + +| Condition | Access Method | Notes | +|---|---|---| +| Internet up | Nextcloud WebDAV / Desktop Client / Mobile App | Full sync, versioning, activity logs | +| Internet up | NFS direct (read-only recommended) | For bulk access; run `occ files:scan` after writes | +| Internet down | Emergency VM → NFS mount | Full read/write at LAN speed | +| Internet down | NFS mount on Mac (direct) | Works natively; run `occ files:scan` after | +| Internet down | NFS mount on Windows | Limited; WSL2 or OpenSSH recommended | +| Internet restored | Run `occ files:scan` | Reconciles any direct NFS writes with Nextcloud | + +--- + +## Important Reminders + +- Always run `occ files:scan` after writing files directly to the NFS share +- Keep a Proxmox snapshot of the Emergency VM +- Use Redis for Nextcloud file locking when data is on NFS +- Ensure `www-data` UID matches between the Nextcloud server and any direct NFS clients +- The `_netdev` fstab option is essential on the Nextcloud server to prevent boot failures if the NFS share is temporarily unavailable