# TrueNAS Scale + Nextcloud Integration

## Architecture

```
┌─────────────────┐         ┌──────────────────┐
│   Proxmox VM    │         │  TrueNAS Scale   │
│  (LemonSec)     │◄───────►│   VM             │
│                 │         │                  │
│ ┌─────────────┐ │         │ ┌──────────────┐ │
│ │   Traefik   │ │  HTTP   │ │  Nextcloud   │ │
│ │   (443)     │◄├─────────┤►│   App        │ │
│ └─────────────┘ │         │ └──────────────┘ │
│        │        │         └──────────────────┘
│        ▼        │
│ ┌─────────────┐ │
│ │  Authelia   │ │ (Optional SSO)
│ └─────────────┘ │
└─────────────────┘
```

## Step 1: Configure TrueNAS Nextcloud

### In TrueNAS Scale Web UI:

1. **Apps** → **Available Applications** → **Nextcloud**
2. **Install** with these settings:
   - **Application Name**: `nextcloud`
   - **Nextcloud Config**:
     - **Nextcloud URL**: `https://cloud.lemonlink.eu` (your domain)
     - **Username**: `admin`
     - **Password**: Generate strong password
   - **Networking**:
     - **Web Port**: `9001` (or any free port)
   - **Storage**:
     - Set up your data pool
   - **Enable**: True

3. **Wait** for installation to complete

4. **Note the Node Port**: TrueNAS will show the port (e.g., `9001`)

## Step 2: Configure LemonSec

### Update .env

```bash
# Edit .env
TRUENAS_IP=192.168.1.100        # Your TrueNAS IP
TRUENAS_NEXTCLOUD_PORT=9001      # Nextcloud port on TrueNAS
```

### Choose Authentication Mode

Edit `docker-compose.external.yml` and pick your authentication:

#### Option A: Nextcloud Native Auth (Recommended for Families)
- Family members use Nextcloud accounts directly
- No Authelia barrier
- Nextcloud handles its own security

```yaml
labels:
  # No authelia middleware
  - "traefik.http.routers.nextcloud.middlewares=security-headers@file,rate-limit@file"
```

#### Option B: Authelia + Nextcloud (Double Security)
- Authelia login first, then Nextcloud login
- Good for admin accounts

```yaml
labels:
  - "traefik.http.routers.nextcloud.middlewares=authelia@docker,security-headers@file,rate-limit@file"
```

#### Option C: Authelia SSO (One login for both)
- Authelia handles auth, passes to Nextcloud
- Requires OpenID Connect setup in Nextcloud

See "Advanced: SSO Integration" below.

## Step 3: Deploy

```bash
# Start core LemonSec
docker-compose up -d

# Start external routing
docker-compose -f docker-compose.yml -f docker-compose.external.yml up -d
```

## Step 4: Configure Nextcloud

### First Login

1. Go to `https://cloud.lemonlink.eu`
2. Login with TrueNAS Nextcloud admin credentials

### Required Settings

Add to TrueNAS Nextcloud **config.php**:

```php
'trusted_domains' => 
array (
  0 => 'localhost',
  1 => '192.168.1.100',        # TrueNAS IP
  2 => 'cloud.lemonlink.eu',   # Your domain
),
'overwriteprotocol' => 'https',
'overwritehost' => 'cloud.lemonlink.eu',
'overwrite.cli.url' => 'https://cloud.lemonlink.eu',
'trusted_proxies' => 
array (
  0 => '192.168.1.50',         # Proxmox VM IP (Traefik)
),
```

In TrueNAS:
1. **Apps** → **Nextcloud** → **Edit** → **Nextcloud Config**
2. Add to **Additional Environments**:
   ```
   OVERWRITEPROTOCOL=https
   OVERWRITEHOST=cloud.lemonlink.eu
   TRUSTED_PROXIES=192.168.1.50
   ```

### Fix WebDAV/Calendar Sync

Create file `fix-wellknown.yml` in Traefik dynamic config:

```yaml
http:
  middlewares:
    nextcloud-wellknown:
      redirectRegex:
        regex: "^https://(.*)/.well-known/(card|cal)dav"
        replacement: "https://cloud.lemonlink.eu/remote.php/dav/"
        permanent: true
```

Add middleware to Nextcloud router:
```yaml
- "traefik.http.routers.nextcloud.middlewares=...,nextcloud-wellknown"
```

## Step 5: Family Access

### Create Family Accounts

1. Login as Nextcloud admin
2. **Settings** → **Users** → **Create user**
3. Create accounts for each family member

### Share the URL

Tell your family:
- **URL**: `https://cloud.lemonlink.eu`
- **Login**: Their individual username/password
- **Apps**: Web, Desktop, Mobile apps available

### Mobile/Desktop Setup

**iOS/Android:**
1. Download Nextcloud app
2. Enter server: `https://cloud.lemonlink.eu`
3. Login with credentials

**Desktop:**
1. Download from nextcloud.com/install
2. Same server URL
3. Enable auto-sync

## Troubleshooting

### "Access through untrusted domain"

Add your domain to TrueNAS Nextcloud config:
```bash
# Shell into TrueNAS Nextcloud pod
k3s kubectl exec -it -n ix-nextcloud nextcloud-xxx -- /bin/sh

# Edit config
cd /var/www/html/config
vi config.php
# Add 'cloud.lemonlink.eu' to trusted_domains
```

### Slow Uploads

Increase timeouts in Traefik:
```yaml
labels:
  - "traefik.http.services.nextcloud.loadbalancer.responseforwarding.flushinterval=100ms"
```

### Large File Uploads (Nextcloud default limit)

In TrueNAS Nextcloud:
1. **Apps** → **Nextcloud** → **Edit**
2. **PHP Configuration**:
   - **Upload Max Size**: `10G` (or your limit)
   - **Memory Limit**: `1G`

### HTTPS Redirect Loop

Ensure these are set in Nextcloud:
```php
'overwriteprotocol' => 'https',
'trusted_proxies' => ['192.168.1.50'],
```

## Advanced: Authelia SSO Integration

If you want single sign-on (login once, access Nextcloud without second login):

### 1. Configure Authelia OpenID Connect

Add to `authelia/configuration.yml`:

```yaml
identity_providers:
  oidc:
    clients:
      - client_id: nextcloud
        client_name: Nextcloud
        client_secret: ${NEXTCLOUD_OAUTH_SECRET}  # Generate with openssl rand -hex 32
        public: false
        authorization_policy: one_factor
        require_pkce: true
        pkce_challenge_method: S256
        redirect_uris:
          - https://cloud.lemonlink.eu/apps/user_oidc/code
        scopes:
          - openid
          - profile
          - email
          - groups
```

### 2. Install OIDC App in Nextcloud

1. Nextcloud → **Apps** → **Search**: "OpenID Connect user backend"
2. **Enable**
3. **Settings** → **Administration** → **OpenID Connect**
4. Configure:
   - **Provider name**: Authelia
   - **Client ID**: nextcloud
   - **Client Secret**: (from above)
   - **Discovery endpoint**: `https://auth.lemonlink.eu/.well-known/openid-configuration`
   - **Scope**: `openid profile email groups`
   - **User ID mapping**: `preferred_username`

### 3. Optional: Disable Authelia on Nextcloud route

Since Nextcloud now handles auth via Authelia OIDC:
```yaml
# Remove authelia@docker middleware
- "traefik.http.routers.nextcloud.middlewares=security-headers@file,rate-limit@file"
```

## Migration from NPM

If you have existing NPM configuration:

1. **Export NPM config**: Settings → Export
2. **Note custom locations**: Proxy Hosts → Edit → Advanced
3. **Recreate in Traefik**:
   - Each NPM Proxy Host = One Traefik router
   - NPM Advanced config = Traefik middlewares
4. **Test** one service at a time
5. **Disable NPM** only after everything works

## Security Notes

- TrueNAS Nextcloud should not be exposed directly (no port forward to TrueNAS)
- All traffic goes through Traefik (single entry point)
- Consider fail2ban on TrueNAS for extra protection
- Regular Nextcloud updates via TrueNAS UI