stura-infra/hosts/nextcloud/README.md

# Nextcloud Host

Nextcloud 31 instance at 141.56.51.16 running in an LXC container.

## Overview

- **Hostname**: cloud
- **FQDN**: cloud.htw.stura-dresden.de
- **IP Address**: 141.56.51.16
- **Type**: Proxmox LXC Container
- **Services**: Nextcloud, PostgreSQL, Redis (caching + locking), Nginx, Nullmailer

## Services

### Nextcloud

Nextcloud 31 provides file hosting and collaboration:
- **Admin user**: administration
- **Max upload size**: 1GB
- **Database**: PostgreSQL (via Unix socket)
- **Caching**: Redis (via Unix socket)
- **Default phone region**: DE (Germany)
- **HTTPS**: Enabled via Nginx reverse proxy
- **Log level**: 4 (warnings and errors)
- **Maintenance window**: 4 AM (prevents maintenance during business hours)

**Pre-installed apps:**
- Calendar
- Deck (Kanban board)
- Tasks
- Notes
- Contacts

### PostgreSQL

Database backend for Nextcloud:
- **Database name**: nextcloud
- **User**: nextcloud
- **Connection**: Unix socket (`/run/postgresql`)
- **Privileges**: Full access to nextcloud database

### Redis

Two Redis instances for performance:
- **Cache**: General caching via `/run/redis-nextcloud/redis.sock`
- **Locking**: Distributed locking mechanism
- **Port**: 0 (Unix socket only)
- **User**: nextcloud

### Nginx

Reverse proxy with recommended settings:
- **Gzip compression**: Enabled
- **Optimization**: Enabled
- **Proxy settings**: Enabled
- **TLS**: Enabled with ACME certificates
- **Access logs**: Disabled (privacy)
- **Error logs**: Only emergency level (`/dev/null emerg`)

### Nullmailer

Simple mail relay for sending email notifications:
- **Relay host**: mail.stura.htw-dresden.de:25
- **From address**: files@stura.htw-dresden.de
- **HELO host**: cloud.htw.stura-dresden.de
- **Protocol**: SMTP (port 25, no auth)

Nextcloud uses Nullmailer's sendmail interface to send email notifications.

## Deployment

See the [main README](../../README.md) for deployment methods.

### Initial Installation

**Using nixos-anywhere:**
```bash
nix run github:nix-community/nixos-anywhere -- --flake .#nextcloud --target-host root@141.56.51.16
```

**Using container tarball:**
```bash
nix build .#containers-nextcloud
scp result/tarball/nixos-system-x86_64-linux.tar.xz root@proxmox-host:/var/lib/vz/template/cache/
pct create 116 /var/lib/vz/template/cache/nixos-system-x86_64-linux.tar.xz \
  --hostname cloud \
  --net0 name=eth0,bridge=vmbr0,ip=141.56.51.16/24,gw=141.56.51.254 \
  --memory 4096 \
  --cores 4 \
  --rootfs local-lvm:20 \
  --unprivileged 1 \
  --features nesting=1
pct start 116
```

**Note**: Nextcloud benefits from more resources (4GB RAM, 20GB disk recommended).

### Updates

```bash
# From local machine
nixos-rebuild switch --flake .#nextcloud --target-host root@141.56.51.16

# Or use auto-generated script
nix run .#nextcloud-update
```

## Post-Deployment Steps

After deploying for the first time:

1. **Set admin password:**
   ```bash
   echo "your-secure-password" > /var/lib/nextcloud/adminpassFile
   chmod 600 /var/lib/nextcloud/adminpassFile
   chown nextcloud:nextcloud /var/lib/nextcloud/adminpassFile
   ```

2. **Access the web interface:**
   ```
   https://cloud.htw.stura-dresden.de
   ```

3. **Complete initial setup:**
   - Log in with admin credentials (user: administration)
   - Review security & setup warnings
   - Configure background jobs (cron is already configured via NixOS)

4. **Configure additional apps:**
   - Navigate to Apps section
   - Enable/disable apps as needed
   - Pre-installed apps: Calendar, Deck, Tasks, Notes, Contacts

5. **Configure trusted domains** (if needed):
   - Current trusted domains: cloud.htw.stura-dresden.de, www.cloud.htw.stura-dresden.de
   - Edit via NixOS config if you need to add more domains

6. **Test email notifications** (optional):
   - Navigate to Settings → Administration → Basic settings
   - Send test email
   - Verify email delivery through Nullmailer relay

7. **Configure user authentication:**
   - Add users manually, or
   - Configure LDAP/OAuth if using external identity provider

## Integration with Proxy

The central proxy at 141.56.51.1 handles:
- **SNI routing**: Routes HTTPS traffic for cloud.htw.stura-dresden.de
- **HTTP routing**: Routes HTTP traffic and redirects to HTTPS
- **ACME challenges**: Forwards certificate verification requests

This host manages its own ACME certificates. Nginx handles TLS termination.

## Troubleshooting

### Redis connection issues

If Nextcloud shows "Redis not available" errors:

```bash
# Check Redis status
systemctl status redis-nextcloud

# Check socket exists and permissions
ls -l /run/redis-nextcloud/redis.sock

# Test Redis connection
redis-cli -s /run/redis-nextcloud/redis.sock ping

# View Redis logs
journalctl -u redis-nextcloud -f
```

**Solution**: Ensure Redis is running and the nextcloud user has access to the socket.

### PostgreSQL permissions

If Nextcloud cannot connect to the database:

```bash
# Check PostgreSQL status
systemctl status postgresql

# Check database exists
sudo -u postgres psql -c "\l" | grep nextcloud

# Check user and permissions
sudo -u postgres psql -c "\du" | grep nextcloud

# Test connection as nextcloud user
sudo -u nextcloud psql -d nextcloud -c "SELECT version();"

# View PostgreSQL logs
journalctl -u postgresql -f
```

**Solution**: Ensure the nextcloud database and user exist with proper permissions.

### Upload size limits

If large file uploads fail:

```bash
# Check Nextcloud upload size setting
grep -i "upload" /var/lib/nextcloud/config/config.php

# Check PHP-FPM settings
systemctl status phpfpm-nextcloud

# View PHP error logs
tail -f /var/log/phpfpm-nextcloud.log
```

**Solution**: The max upload is set to 1GB via `maxUploadSize`. If you need larger files, modify the NixOS configuration.

### Opcache configuration

If PHP performance is poor:

```bash
# Check PHP opcache settings
php -i | grep opcache

# Check opcache status via Nextcloud admin panel
# Settings → Administration → Overview → PHP

# Restart PHP-FPM to clear cache
systemctl restart phpfpm-nextcloud
```

**Solution**: The opcache interned strings buffer is set to 32MB. If you see opcache errors, this may need adjustment.

### Mail relay issues

If email notifications are not being sent:

```bash
# Check Nullmailer status
systemctl status nullmailer

# Check mail queue
mailq

# View Nullmailer logs
journalctl -u nullmailer -f

# Test mail relay
echo "Test message" | mail -s "Test" user@example.com

# Check Nextcloud mail settings
sudo -u nextcloud php /var/lib/nextcloud/occ config:list | grep mail
```

**Solution**: Verify the mail relay host (mail.stura.htw-dresden.de) is reachable and accepting SMTP connections on port 25.

### ACME certificate issues

If HTTPS is not working:

```bash
# Check ACME certificate status
systemctl status acme-cloud.htw.stura-dresden.de

# View ACME logs
journalctl -u acme-cloud.htw.stura-dresden.de -f

# Check Nginx HTTPS configuration
nginx -t

# View Nginx error logs
journalctl -u nginx -f
```

**Solution**: Ensure DNS points to proxy (141.56.51.1) and the proxy forwards ACME challenges to this host.

### Maintenance mode stuck

If Nextcloud is stuck in maintenance mode:

```bash
# Disable maintenance mode
sudo -u nextcloud php /var/lib/nextcloud/occ maintenance:mode --off

# Check status
sudo -u nextcloud php /var/lib/nextcloud/occ status

# Run system check
sudo -u nextcloud php /var/lib/nextcloud/occ check
```

**Solution**: Maintenance mode is automatically disabled after updates, but can sometimes get stuck.

## Files and Directories

- **Nextcloud data**: `/var/lib/nextcloud/`
- **Admin password**: `/var/lib/nextcloud/adminpassFile`
- **Configuration**: `/var/lib/nextcloud/config/config.php`
- **Apps**: `/var/lib/nextcloud/apps/`
- **User files**: `/var/lib/nextcloud/data/`
- **PostgreSQL data**: `/var/lib/postgresql/`
- **Redis socket**: `/run/redis-nextcloud/redis.sock`

## Network

- **Interface**: eth0 (LXC container)
- **IP**: 141.56.51.16/24
- **Gateway**: 141.56.51.254
- **Firewall**: Ports 80, 443 allowed

## Configuration Details

- **Version**: Nextcloud 31
- **Database type**: PostgreSQL
- **Caching**: Redis (APCU disabled)
- **HTTPS**: Yes (enforced via forceSSL)
- **Trusted domains**:
  - cloud.htw.stura-dresden.de
  - www.cloud.htw.stura-dresden.de
- **PHP opcache**: Interned strings buffer 32MB
- **Maintenance window**: 4 AM (hour 4)
- **Log level**: 4 (warnings and errors)

## Useful Commands

```bash
# Run occ commands (Nextcloud CLI)
sudo -u nextcloud php /var/lib/nextcloud/occ <command>

# List all users
sudo -u nextcloud php /var/lib/nextcloud/occ user:list

# Scan files for changes
sudo -u nextcloud php /var/lib/nextcloud/occ files:scan --all

# Run background jobs
sudo -u nextcloud php /var/lib/nextcloud/occ background:cron

# Update apps
sudo -u nextcloud php /var/lib/nextcloud/occ app:update --all

# Check for Nextcloud updates
sudo -u nextcloud php /var/lib/nextcloud/occ update:check
```

## See Also

- [Main README](../../README.md) - Deployment methods and architecture
- [Proxy README](../proxy/README.md) - How the central proxy routes traffic
- [Nextcloud Documentation](https://docs.nextcloud.com/)
- [Nextcloud Admin Manual](https://docs.nextcloud.com/server/stable/admin_manual/)
- [NixOS Nextcloud Options](https://search.nixos.org/options?query=services.nextcloud)