# Installation and Configuration Guide

Step-by-step instructions for installing, configuring, and setting up the Nextcloud WHMCS module, including Nextcloud server preparation, WHMCS integration, email templates, and product configuration.

# WHMCS setup (install/update)

### Nextcloud module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-nextcloud.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/) | [FAQ](https://faq.puqcloud.com/)

## System requirements

| Requirement | Minimum version |
|-------------|-----------------|
| **PHP** | 8.2 or higher |
| **WHMCS** | 9.x or higher |
| **ionCube Loader** | v13 or newer (v14, v15) |

> **Note:** The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server.

---

## Download

The module can be ordered and downloaded from PUQ Cloud:

- **Order / Download:** [https://puqcloud.com/whmcs-module-nextcloud.php](https://puqcloud.com/whmcs-module-nextcloud.php)
- **FAQ:** [https://faq.puqcloud.com/](https://faq.puqcloud.com/)
- **Direct download link for the latest version:**

```
wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php82/PUQ_WHMCS-Nextcloud-latest.zip
```

> Older module versions for WHMCS 8 are available in PHP-specific directories:
> - PHP 7.4: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php74/)
> - PHP 8.1: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php81/)

After downloading, extract the archive:

```
unzip PUQ_WHMCS-Nextcloud-latest.zip
```

---

## Installation

### Step 1: Upload files

Extract the module archive and copy the `puqNextcloud` directory to the WHMCS servers module directory:

```
WHMCS_WEB_DIR/modules/servers/puqNextcloud
```

### Step 2: Add server

Navigate to **System Settings** → **Servers** → **Add New Server**:

1. Enter the correct **Name** and **Hostname**
2. In Server Details, select the **PUQ Nextcloud** module
3. Enter valid Nextcloud web interface credentials (username and password)
4. Click **Test connection** to verify

### Step 3: Create product

Navigate to **System Settings** → **Products/Services** → **Create a New Product**:

1. Select the **PUQ Nextcloud** module in the Module settings section
2. Configure the product parameters

---

## Update

### Step 1: Backup

Before updating, it is recommended to back up:
- WHMCS database
- Module files in `modules/servers/puqNextcloud/`

### Step 2: Upload new files

Download and extract the new version, then overwrite all files in:

```
WHMCS_WEB_DIR/modules/servers/puqNextcloud/
```

### Step 3: Verification

1. Log in to the WHMCS admin panel
2. Check the module is functioning correctly
3. Verify product settings

> **Important (v3.0):** Product reconfiguration is required after updating to version 3.0.


<!-- sync:8913e1a487cbd888 -->

# Setup guide: Nextcloud setup

### Nextcloud module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-nextcloud.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/) | [FAQ](https://faq.puqcloud.com/)

## Nextcloud including Nextcloud Office on Debian10 with nginx, MariaDB, PHP 8.1, Let's Encrypt, Redis, Fail2ban and ufw

This guide covers the complete installation and configuration of a Nextcloud server from scratch on Debian, including all required components.

---

## 1. Preparation and installation of nginx web server

Install required packages:

```bash
apt-get install -y \
  curl wget git apt-transport-https gnupg2 \
  imagemagick libmagickcore-6.q16-6 libmagickwand-6.q16-6 \
  software-properties-common dirmngr lsb-release ca-certificates \
  unzip
```

### Configure hostname

Edit `/etc/hosts` with server IP and FQDN:

```
127.0.0.1 localhost
YOUR_SERVER_IP your.domain.com
```

Edit `/etc/hostname`:

```
your.domain.com
```

Reboot the system:

```bash
reboot
```

### Install nginx

Add the nginx repository and install:

```bash
apt-get install -y nginx
```

Remove conflicting web servers:

```bash
apt-get remove -y apache2
```

Enable and start nginx:

```bash
systemctl enable nginx
systemctl start nginx
```

### Configure nginx

Backup the default configuration and create a custom one:

```bash
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
```

Key nginx.conf settings include:
- Worker processes and connections
- JSON-formatted logging
- Real IP handling
- File caching parameters
- Security headers

Create required directories:

```bash
mkdir -p /var/log/nextcloud /var/nc_data /var/www/letsencrypt/.well-known/acme-challenge /etc/letsencrypt/rsa-certs /etc/letsencrypt/ecc-certs
```

---

## 2. Installation and configuration of PHP 8.1 (FPM)

Install PHP packages:

```bash
apt-get install -y \
  php-common php8.1-fpm php8.1-gd php8.1-curl php8.1-xml \
  php8.1-zip php8.1-intl php8.1-mbstring php8.1-bz2 \
  php8.1-ldap php8.1-apcu php8.1-bcmath php8.1-gmp \
  php8.1-imagick php8.1-igbinary php8.1-mysql php8.1-redis \
  php8.1-smbclient php8.1-cli php8.1-opcache php8.1-readline \
  imagemagick
```

Optional packages for LDAP/Samba:

```bash
apt-get install -y ldap-utils nfs-common cifs-utils
```

### Configure timezone

```bash
timedatectl set-timezone Europe/Warsaw
```

### Key PHP optimizations

Backup and configure PHP settings:

- **Memory limit:** 1G
- **Max execution time:** 3600 seconds
- **Upload max filesize:** 10G
- **Post max size:** 10G
- **OPCache enabled:** memory 256MB, max files 100000
- Session cookie security enabled
- ImageMagick policy permissions updated for PS, EPS, PDF, XPS files

---

## 3. Installation and configuration of MariaDB 10.8

### Database security hardening

```bash
mysql_secure_installation
```

- Set root password
- Remove anonymous users
- Disable remote root login
- Remove test database

### Database configuration

Custom MariaDB configuration (`/etc/mysql/my.cnf`):
- Character set: utf8mb4
- Default storage engine: InnoDB
- Max connections: 200
- Binlog format: ROW
- Transaction isolation: READ-COMMITTED

### Create Nextcloud database

```sql
CREATE DATABASE nextclouddb CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER nextclouddbuser@localhost identified by 'nextclouddbpassword';
GRANT ALL PRIVILEGES on nextclouddb.* to nextclouddbuser@localhost;
FLUSH privileges;
```

> **Important:** Replace `nextclouddbpassword` with a strong password.

---

## 4. Installing and configuring Redis

Install and configure Redis:

```bash
apt-get install -y redis-server
```

Configuration:
- Port: disabled (set to 0)
- Unix socket enabled with permissions 770
- Max clients: 10240

```bash
usermod -aG redis www-data
```

Set kernel parameter:

```bash
echo "vm.overcommit_memory = 1" >> /etc/sysctl.conf
```

> Reboot the system before Nextcloud installation.

---

## 5. Installation and optimization of Nextcloud (incl. SSL)

### Certbot and Let's Encrypt setup

```bash
apt-get install -y certbot python3-certbot-nginx
```

### nginx vhost configuration

Create `/etc/nginx/conf.d/nextcloud.conf` with:
- Upstream handler: PHP-FPM socket
- HTTP to HTTPS redirect
- SSL certificates from Let's Encrypt
- TLS 1.2 and 1.3 protocols
- Client max body size: 10G
- GZIP compression
- Security headers (HSTS, X-Frame-Options, etc.)
- Nextcloud-specific location blocks

### Generate SSL certificate

```bash
certbot --nginx -d yourdomain.com
```

Auto-renewal crontab:

```
0 12 * * * /usr/bin/certbot renew --quiet
```

### Install Nextcloud

Download and verify:

```bash
cd /usr/local/src
wget https://download.nextcloud.com/server/releases/latest.zip
wget https://download.nextcloud.com/server/releases/latest.zip.md5
md5sum -c latest.zip.md5 < latest.zip
```

Extract and set permissions:

```bash
unzip latest.zip -d /var/www
chown -R www-data:www-data /var/www/nextcloud
```

### Silent installation

```bash
sudo -u www-data php /var/www/nextcloud/occ maintenance:install \
  --database "mysql" \
  --database-name "nextclouddb" \
  --database-user "nextclouddbuser" \
  --database-pass "nextclouddbpassword" \
  --admin-user "YourNextcloudAdmin" \
  --admin-pass "YourNextcloudAdminPassword" \
  --data-dir "/var/nc_data"
```

### Configure trusted domain

```bash
sudo -u www-data php /var/www/nextcloud/occ config:system:set trusted_domains 0 --value=your.domain.com
```

### CLI URL configuration

```bash
sudo -u www-data php /var/www/nextcloud/occ config:system:set overwrite.cli.url --value=https://your.domain.com
```

### Extended configuration

Create `/var/www/nextcloud/config/tweaks.config.php` with settings including:
- Activity expiration: 14 days
- Authentication bruteforce protection enabled
- Blacklisted files: .htaccess, Thumbs.db
- Default phone region
- Preview providers: PNG, JPEG, GIF, BMP, PDF, MP3, TXT, MarkDown
- Redis configuration with Unix socket
- Trashbin retention: auto, 7 days
- Logging: file at `/var/log/nextcloud/nextcloud.log`, level 2
- Log rotation: 100MB

### App management

```bash
sudo -u www-data php /var/www/nextcloud/occ app:disable survey_client
sudo -u www-data php /var/www/nextcloud/occ app:disable firstrunwizard
sudo -u www-data php /var/www/nextcloud/occ app:enable admin_audit
sudo -u www-data php /var/www/nextcloud/occ app:enable files_pdfviewer
```

Optional Nextcloud Office installation:

```bash
sudo -u www-data php /var/www/nextcloud/occ app:install richdocuments
sudo -u www-data php /var/www/nextcloud/occ app:install richdocumentscode
```

### Restart services

```bash
systemctl stop nginx php8.1-fpm
systemctl restart mysql php8.1-fpm redis nginx
```

### Set up cron

As www-data user:

```
*/5 * * * * php -f /var/www/nextcloud/cron.php > /dev/null 2>&1
```

Reconfigure to cron mode:

```bash
sudo -u www-data php /var/www/nextcloud/occ background:cron
```

### Pin packages

Prevent unwanted package updates:

```bash
apt-mark hold nginx* redis* mysql* galera* mariadb* php*
```

![Nextcloud setup](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-ihmixrn2.png)
*15-nextcloud-setup.png*

---

## 6. System hardening with Fail2ban and UFW

### Fail2ban configuration

Install Fail2ban:

```bash
apt-get install -y fail2ban
```

Create Nextcloud filter (`/etc/fail2ban/filter.d/nextcloud.conf`):
- Regex patterns for login failures
- Trusted domain errors
- Date pattern for JSON log format

Create Nextcloud jail (`/etc/fail2ban/jail.d/nextcloud.local`):

```ini
[nextcloud]
backend = auto
enabled = true
port = 80,443
protocol = tcp
maxretry = 5
bantime = 3600
findtime = 36000
logpath = /var/log/nextcloud/nextcloud.log
```

### UFW firewall configuration

```bash
ufw allow 80/tcp comment "LetsEncrypt(http)"
ufw allow 443/tcp comment "LetsEncrypt(https)"
ufw allow 22/tcp comment "SSH"
ufw enable
```


<!-- sync:bcd468c54b1ee0e8 -->

# Setup guide: WHMCS setup

### Nextcloud module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-nextcloud.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/) | [FAQ](https://faq.puqcloud.com/)

## System requirements

| Requirement | Minimum version |
|-------------|-----------------|
| **PHP** | 8.2 or higher |
| **WHMCS** | 9.x or higher |
| **ionCube Loader** | v13 or newer (v14, v15) |

> **Note:** The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server.

> Older module versions for WHMCS 8 are available in PHP-specific directories:
> - PHP 7.4: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php74/)
> - PHP 8.1: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php81/)

---

## Step 1: Download the module

```bash
wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/php82/PUQ_WHMCS-Nextcloud-latest.zip
```

---

## Step 2: Extract the archive

```bash
unzip PUQ_WHMCS-Nextcloud-latest.zip
```

---

## Step 3: Copy module files

Copy the `puqNextcloud` directory to:

```
WHMCS_WEB_DIR/modules/servers/
```

---

## Step 4: Add server in WHMCS

Navigate to **System Settings** → **Servers** → **Add New Server**

1. Enter the correct **Name** and **Hostname**
2. In the Server Details section, select the **PUQ Nextcloud** module
3. Enter valid Nextcloud web interface credentials (username and password)
4. Click **Test connection** to verify the connection

![Add server - general settings](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-bkwj9tmc.png)
*04-add-server-1.png*

![Add server - module settings](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-3dvujzek.png)
*05-add-server-2.png*

---

## Step 5: Create product in WHMCS

Navigate to **System Settings** → **Products/Services** → **Create a New Product**

Select the **PUQ Nextcloud** module in the Module settings section.

![WHMCS product module settings](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-mfto7uhh.png)
*06-whmcs-setup.png*


<!-- sync:f476537ec16fd78c -->

# Email Template (puqNextcloud notification disk limit)

### Nextcloud module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-nextcloud.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/) | [FAQ](https://faq.puqcloud.com/)

## Creating the email template

Navigate to **System Settings** → **Email Templates** → **Create New Email Template**

---

## Template configuration

| Parameter | Value |
|-----------|-------|
| **Email Type** | Product/service |
| **Unique Name** | puqNextcloud Notification disk limit |

---

## Email subject

```
Disk space usage {$disk_used_percentage} % - {$username}
```

---

## Email body

```
Dear {$client_name},

We would like to inform you that the disk space usage for your
product/service has reached the notification threshold.

Product/Service: {$service_product_name}
Due Date: {$service_next_due_date}
Username: {$username}

Disk Limit: {$disk_limit}
Disk Used: {$disk_used} ({$disk_used_percentage}%)
Disk Free: {$disk_free} ({$disk_free_percentage}%)

Please take the necessary actions to manage your disk space.

{$signature}
```

---

## Available template variables

The following custom variables are passed to the email template by the module:

| Variable | Description | Example |
|----------|-------------|---------|
| `{$username}` | Nextcloud username | john-42 |
| `{$disk_limit}` | Total disk quota with unit | 10 GB |
| `{$disk_used}` | Used disk space with unit | 8.5 GB |
| `{$disk_free}` | Free disk space with unit | 1.5 GB |
| `{$disk_used_percentage}` | Used space as percentage | 85 |
| `{$disk_free_percentage}` | Free space as percentage | 15 |

In addition, all standard WHMCS product/service merge fields are available (e.g. `{$client_name}`, `{$service_product_name}`, `{$service_next_due_date}`, `{$signature}`).

> **Note:** Notifications are sent automatically during the WHMCS daily cron execution when disk usage reaches the threshold configured in the product settings ("Notify at %").

---

## Screenshots

![Email template creation](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-boerm29r.png)
*07-email-template-1.png*

![Email template configuration](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-edfurx21.png)
*08-email-template-2.png*


<!-- sync:648e8836e96571fe -->

# Add server (Nextcloud server)

### Nextcloud module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-nextcloud.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/) | [FAQ](https://faq.puqcloud.com/)

## Adding a Nextcloud server to WHMCS

Navigate to **System Settings** → **Servers** → **Add New Server**

---

### Step 1: General settings

Enter the correct **Name** and **Hostname** for your Nextcloud server.

- **Name** — a descriptive name for the server (e.g. "Nextcloud Production")
- **Hostname** — the domain name or IP address of your Nextcloud installation (e.g. `cloud.example.com`)

If your Nextcloud uses a non-standard port, enter it in the **Port** field. Check the **Secure** checkbox if your server uses HTTPS (recommended).

![Add server - general settings](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-tbw31i8i.png)
*04-add-server-1.png*

---

### Step 2: Module settings

1. In the Server Details section, select the **PUQ Nextcloud** module from the dropdown
2. Enter valid credentials for the Nextcloud web interface:
   - **Username** — Nextcloud administrator username
   - **Password** — Nextcloud administrator password
3. Click **Test connection** to verify the connection is working correctly

The test connection verifies that the module can reach the Nextcloud OCS API (`/ocs/v1.php/cloud/users/`) and authenticate with the provided credentials.

![Add server - module settings](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-kgkr1ybc.png)
*05-add-server-2.png*

> **Important:** The Nextcloud user must have **administrator privileges** to manage users via the API. The module uses the Nextcloud OCS API v1 with HTTP Basic Authentication to create, modify, suspend, and delete user accounts.


<!-- sync:b6b9d7053e69bbaf -->

# Product Configuration

### Nextcloud module **[WHMCS](https://puqcloud.com/link.php?id=77)**
#####  [Order now](https://puqcloud.com/whmcs-module-nextcloud.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Nextcloud/) | [FAQ](https://faq.puqcloud.com/)

## Add new product to WHMCS

Navigate to **System Settings** → **Products/Services** → **Create a New Product**

Select the **PUQ Nextcloud** module in the Module settings section.

---

## Configuration parameters

| Parameter | Description |
|-----------|-------------|
| **License key** | A pre-purchased license key for the PUQ Nextcloud module. The license must be active for correct operation. After saving, the verification status is displayed below the field. |
| **Disk size** | Allocated disk space for the Nextcloud user. Set to **0** for unlimited quota. Minimum value: 0. |
| **Disk unit** | Unit used for the allocated disk space. Available options: **MB**, **GB**, **TB**, **PB**. |
| **Notify at %** | Disk usage threshold in percent (1–100). A notification email is sent when usage reaches this value. Default: **90**. Set to **0** to disable notifications. |
| **Email template** | Email template used for low disk space notifications. Select from available Product/service type email templates. The template must be created manually in WHMCS (see [Email Template](#) page). |
| **Save history (days)** | Number of days to store disk usage statistics in WHMCS. Older records are automatically deleted during cron execution. |
| **Group** | Nextcloud group assigned to the user on the server side. The group is created automatically if it does not exist. When changing packages, the user is removed from all groups and added to the new group. |
| **Username rule** | Rule for automatic username generation using macros (see below). Default: `{client_id}-{service_id}`. |
| **Password rule** | Password generation rule in `length:charset` format (see below). Default: `12:123456789QAZWSXEDCRFVTGBYHNUJMIKqazwsxedcrfvtgbyhnujmikolp`. |
| **Link to instruction** | URL to instructions displayed as a button in the client area. Leave empty to hide the button. |
| **Show password** | Defines how the password is shown in the client area. Options: **Show button** (hidden by default, revealed on click), **Plain text** (always visible), **No** (hidden, no option to reveal). |

---

## Username rule — available macros

The username is generated automatically when a new account is created. You can use the following macros:

| Macro | Description | Example |
|-------|-------------|---------|
| `{client_id}` | WHMCS client ID | 123 |
| `{service_id}` | WHMCS service ID | 456 |
| `{unixtime}` | Current Unix timestamp | 1707638400 |
| `{year}` | Current year | 2026 |
| `{month}` | Current month (01–12) | 02 |
| `{day}` | Current day (01–31) | 12 |
| `{hour}` | Current hour (00–23) | 14 |
| `{minute}` | Current minute (00–59) | 30 |
| `{second}` | Current second (00–59) | 45 |
| `{random_digit_x}` | x random digits (0–9) | `{random_digit_4}` → 7394 |
| `{random_letter_x}` | x random letters (A–Z, a–z) | `{random_letter_6}` → aBcDeF |

**Examples:**
- `{client_id}-{service_id}` → `123-456`
- `nc-{random_digit_6}` → `nc-384729`
- `user-{client_id}-{random_letter_4}` → `user-123-aBcD`

> **Note:** If the generated username already exists on the Nextcloud server, the module automatically appends a counter: `username-1`, `username-2`, etc.

---

## Password rule — format

The password rule uses the format `length:charset`, where:
- **length** — number of characters to generate
- **charset** — set of characters to use

**Examples:**
- `12:abcdefghijklmnopqrstuvwxyz0123456789` — 12 lowercase alphanumeric characters
- `16:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789` — 16 mixed-case alphanumeric
- `20:0123456789` — 20 digits only

> If no rule is specified, a 12-character password is generated from a default character set.

---

## Important notes

> **Warning:** This module works only as a **server module** (Products/Services). It cannot be used as an addon product. Attempting to use it with addon products will result in an error.

---

## Screenshot

![Product configuration settings](https://doc.puq.info/uploads/images/gallery/2026-02/embedded-image-8awykoul.png)
*09-product-configuration.png*


<!-- sync:a190893365a37157 -->