# Nextcloud

Self-hosted Nextcloud file storage and collaboration platform with MariaDB, Redis caching, automatic HTTPS, and EBS data persistence. Production ready.

# 1.0.0 -

# Nextcloud AMI Documentation

Self-hosted cloud storage and collaboration platform on AWS.

## Overview

This AMI provides a production-ready Nextcloud installation with MariaDB database, Redis caching, and optional HTTPS via Let's Encrypt. All data is stored on a separate EBS volume for easy backup and persistence.

## Requirements

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| Instance Type | t3.small | t3.medium or larger |
| RAM | 2 GB | 4 GB+ |
| Root Volume | 8 GB | 10 GB |
| Data Volume (EBS) | 20 GB | 50 GB+ (based on storage needs) |

## Quick Start

### Option 1: Interactive Configuration

1. Launch the AMI with an attached EBS volume for data storage
2. SSH into the instance:
   ```
   ssh -i your-key.pem ubuntu@your-instance-ip
   ```
3. Run the configuration script:
   ```
   sudo /opt/nextcloud/configure-nextcloud.sh
   ```
4. Follow the prompts to set up your admin account and domain

### Option 2: Automated Configuration (User-Data)

Launch the instance with JSON user-data for automatic configuration:

```json
{
  "admin_user": "admin",
  "admin_password": "YourSecurePassword123",
  "domain": "nextcloud.example.com",
  "https": "yes",
  "email": "admin@example.com"
}
```

#### User-Data Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| admin_user | No | Admin username (default: admin) |
| admin_password | Yes | Admin password (minimum 8 characters) |
| domain | No | Domain name or IP (default: public IP) |
| https | No | Enable HTTPS with Let's Encrypt (yes/no) |
| email | Required for HTTPS | Email for Let's Encrypt notifications |

## Network Ports

| Port | Protocol | Description |
|------|----------|-------------|
| 22 | TCP | SSH access |
| 80 | TCP | HTTP web interface |
| 443 | TCP | HTTPS web interface (when enabled) |

Configure your Security Group to allow these ports from appropriate sources.

## Management Commands

The `nextcloud-cli` utility provides easy management of your Nextcloud installation:

```bash
# Check service status
sudo nextcloud-cli status

# View logs
sudo nextcloud-cli logs

# View logs for specific service
sudo nextcloud-cli logs nextcloud

# Show configuration info
sudo nextcloud-cli info

# Start/stop/restart services
sudo nextcloud-cli start
sudo nextcloud-cli stop
sudo nextcloud-cli restart

# Update to latest version
sudo nextcloud-cli update

# Create backup
sudo nextcloud-cli backup

# Run Nextcloud occ commands
sudo nextcloud-cli occ status
sudo nextcloud-cli occ files:scan --all
sudo nextcloud-cli occ user:list

# Toggle maintenance mode
sudo nextcloud-cli maintenance

# Open shell in Nextcloud container
sudo nextcloud-cli shell

# Open database shell
sudo nextcloud-cli db-shell

# Reset configuration (WARNING: deletes all data)
sudo nextcloud-cli reset
```

## HTTPS Configuration

### Automatic HTTPS with Let's Encrypt

When configuring with a domain name, you can enable automatic HTTPS:

1. Ensure your domain's DNS A record points to your instance's public IP
2. Open ports 80 and 443 in your Security Group
3. Enable HTTPS during configuration and provide a valid email address

The SSL certificate will be automatically obtained and renewed.

### Requirements for HTTPS

- Valid domain name (not an IP address)
- DNS properly configured
- Ports 80 and 443 open
- Valid email address for Let's Encrypt notifications

## Data Storage

All Nextcloud data is stored on the attached EBS volume at `/mnt/nextcloud-data/`:

```
/mnt/nextcloud-data/
├── html/       # Nextcloud application files
├── data/       # User files and data
├── db/         # MariaDB database files
├── certs/      # SSL certificates (if HTTPS enabled)
├── acme/       # Let's Encrypt ACME data
└── backups/    # Backup files (created by backup command)
```

## Backup and Restore

### Creating Backups

```bash
sudo nextcloud-cli backup
```

This creates timestamped backups in `/mnt/nextcloud-data/backups/`:
- Database dump (SQL)
- Data directory archive
- Configuration archive

### Manual Backup

For EBS snapshot backups:

1. Enable maintenance mode:
   ```bash
   sudo nextcloud-cli occ maintenance:mode --on
   ```

2. Create an EBS snapshot from the AWS Console

3. Disable maintenance mode:
   ```bash
   sudo nextcloud-cli occ maintenance:mode --off
   ```

### Restore from Backup

1. Stop Nextcloud:
   ```bash
   sudo nextcloud-cli stop
   ```

2. Restore database:
   ```bash
   docker exec -i nextcloud-db mysql -u nextcloud -p"$(grep DB_PASSWORD /opt/nextcloud/.credentials | cut -d= -f2)" nextcloud < backup_db.sql
   ```

3. Restore data:
   ```bash
   sudo tar -xzf backup_data.tar.gz -C /mnt/nextcloud-data/
   ```

4. Start Nextcloud:
   ```bash
   sudo nextcloud-cli start
   ```

## Updating Nextcloud

To update to the latest stable version:

```bash
sudo nextcloud-cli update
```

This command will:
1. Enable maintenance mode
2. Pull the latest Docker images
3. Restart all containers
4. Run any required upgrades
5. Disable maintenance mode

## Troubleshooting

### Check Container Status

```bash
sudo nextcloud-cli status
docker ps -a
```

### View Logs

```bash
# All logs
sudo nextcloud-cli logs

# Specific service logs
sudo nextcloud-cli logs nextcloud
sudo nextcloud-cli logs nextcloud-db
sudo nextcloud-cli logs nginx-proxy
```

### Common Issues

**Nextcloud not accessible after launch:**
- Wait 2-3 minutes for initial setup to complete
- Check that Security Group allows ports 80/443
- Verify EBS volume is properly attached and mounted

**HTTPS certificate not working:**
- Ensure DNS is properly configured
- Check that ports 80 and 443 are both open
- View acme-companion logs: `sudo nextcloud-cli logs acme-companion`

**Database connection errors:**
- Check database container: `docker logs nextcloud-db`
- Verify database credentials in `/opt/nextcloud/.credentials`

**Permission issues with files:**
- Run file scan: `sudo nextcloud-cli occ files:scan --all`
- Check data directory ownership

### Reset Installation

If you need to start fresh:

```bash
sudo nextcloud-cli reset
```

**WARNING:** This deletes all data and configuration!

## File Locations

| Path | Description |
|------|-------------|
| /opt/nextcloud/ | Main configuration directory |
| /opt/nextcloud/docker-compose.yml | Docker Compose configuration |
| /opt/nextcloud/.credentials | Stored credentials (chmod 600) |
| /opt/nextcloud/config-info.txt | Configuration summary |
| /mnt/nextcloud-data/ | All persistent data |
| /var/log/nextcloud-firstboot.log | First boot log |

## Security Recommendations

1. **Change default admin password** after first login
2. **Enable two-factor authentication** for admin accounts
3. **Regular backups** using EBS snapshots or the backup command
4. **Keep Nextcloud updated** using the update command
5. **Restrict SSH access** in Security Group to your IP only
6. **Use HTTPS** with a valid domain name in production

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  EC2 Instance                    │
│                                                  │
│  ┌──────────────┐  ┌──────────────┐             │
│  │ nginx-proxy  │  │    acme      │  (HTTPS)    │
│  │   :80/:443   │  │  companion   │             │
│  └──────┬───────┘  └──────────────┘             │
│         │                                        │
│  ┌──────▼───────┐                               │
│  │  Nextcloud   │                               │
│  │   Container  │                               │
│  └──────┬───────┘                               │
│         │                                        │
│  ┌──────▼───────┐  ┌──────────────┐             │
│  │   MariaDB    │  │    Redis     │             │
│  │   Database   │  │    Cache     │             │
│  └──────────────┘  └──────────────┘             │
│                                                  │
└─────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────┐
    │   EBS Volume    │
    │ /mnt/nextcloud  │
    │     -data       │
    └─────────────────┘
```

## Support

For issues specific to this AMI deployment, check:
- First boot log: `/var/log/nextcloud-firstboot.log`
- Docker logs: `sudo nextcloud-cli logs`
- Service status: `sudo nextcloud-cli status`

For Nextcloud-specific questions, refer to the official documentation:
- https://docs.nextcloud.com/

## Version Information

- Base OS: Ubuntu 24.04 LTS
- Nextcloud: Latest stable release
- MariaDB: 10.11
- Redis: 7 (Alpine)
- nginx-proxy: Latest
- acme-companion: Latest