nextcloud_nfs_setup/README.md

# 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