# Installation and Configuration Guide Step-by-step instructions for installing, configuring, and setting up the MinIO S3 WHMCS module, including MinIO server preparation, WHMCS integration, email templates, and product configuration. # WHMCS setup (install/update) ## System requirements The module uses ionCube encoding. Your server must meet the following requirements: | Requirement | Minimum | |-------------|---------| | PHP | 8.2 or higher | | WHMCS | 9.x or higher | | ionCube Loader | v13 or newer (v14, v15) | ### Older module versions for WHMCS 8 Older versions of the module are available for download, sorted by PHP version: - PHP 7.4: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php74/) - PHP 8.1: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php81/) --- ## Step 1 — Download the latest version of the module ```bash wget http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php82/PUQ_WHMCS-MinIO-S3-latest.zip ``` All versions of the module are available via the link: [http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/](http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/) --- ## Step 2 — Unzip the archive with the module ```bash unzip PUQ_WHMCS-MinIO-S3-latest.zip ``` --- ## Step 3 — Copy and Replace Copy the `puqMinIOS3` directory from the extracted `PUQ_WHMCS-MinIO-S3` archive to your WHMCS installation: ``` WHMCS_WEB_DIR/modules/servers/ ``` > **Note:** To install and update a module, you must perform one and the same action — download and copy the latest version over the existing files. # Setup guide: MinIO S3 setup ## Section 1 — Installing and configuring the MinIO server Update packages and download the MinIO binary: ```bash sudo apt update wget https://dl.min.io/server/minio/release/linux-amd64/minio ``` Install the binary and set up the MinIO user: ```bash sudo chmod +x minio sudo mv minio /usr/local/bin sudo useradd -r minio-user -s /sbin/nologin sudo chown minio-user:minio-user /usr/local/bin/minio sudo mkdir /usr/local/share/minio sudo chown minio-user:minio-user /usr/local/share/minio sudo mkdir /etc/minio sudo chown minio-user:minio-user /etc/minio ``` Create the environment configuration file `/etc/default/minio`: ```ini MINIO_ACCESS_KEY="minio" MINIO_VOLUMES="/usr/local/share/minio/" MINIO_OPTS="-C /etc/minio --address :9000 --console-address :9001" MINIO_SECRET_KEY="miniostorage" ``` --- ## Section 2 — Installing the Systemd MinIO startup script Create the service file `/etc/systemd/system/minio.service`: ```ini [Unit] Description=MinIO Documentation=https://docs.min.io Wants=network-online.target After=network-online.target AssertFileIsExecutable=/usr/local/bin/minio [Service] WorkingDirectory=/usr/local/ User=minio-user Group=minio-user EnvironmentFile=/etc/default/minio ExecStartPre=/bin/bash -c "if [ -z \"${MINIO_VOLUMES}\" ]; then echo \"Variable MINIO_VOLUMES not set in /etc/default/minio\"; exit 1; fi" ExecStart=/usr/local/bin/minio server $MINIO_OPTS $MINIO_VOLUMES Restart=always LimitNOFILE=65536 TimeoutStopSec=infinity SendSIGKILL=no [Install] WantedBy=multi-user.target ``` --- ## Section 3 — Starting the MinIO Server ```bash sudo systemctl daemon-reload sudo systemctl enable minio sudo systemctl start minio sudo systemctl status minio ``` --- ## Section 4 — Securing Access to MinIO Server with Let's Encrypt SSL/TLS Certificate Install certbot and nginx: ```bash sudo apt update sudo apt install certbot nginx python3-certbot-nginx -y ``` Create the nginx configuration file `/etc/nginx/sites-enabled/minio`: ```nginx server { listen 80 default_server; server_name yourdomain.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name yourdomain.com; ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/yourdomain.com/cert.pem; ssl_session_timeout 20m; ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_prefer_server_ciphers on; ssl_verify_client off; ignore_invalid_headers off; client_max_body_size 0; proxy_buffering off; location / { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Host $http_host; proxy_connect_timeout 300; proxy_http_version 1.1; proxy_set_header Connection ""; chunked_transfer_encoding off; proxy_pass http://localhost:9001; } } ``` Remove the default nginx config and generate SSL certificate: ```bash rm /etc/nginx/sites-enabled/default sudo certbot --nginx -d yourdomain.com sudo service nginx restart ``` Add certificate auto-renewal to crontab: ``` 0 12 * * * /usr/bin/certbot renew --quiet ``` --- ## Default Login Credentials After installation, you can access the MinIO console at `https://yourdomain.com`: - **Username:** `minio` - **Password:** `miniostorage` ![MinIO login screen](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-f7j0fotd.png) # Setup guide: WHMCS setup ## System requirements The module is encoded with ionCube. | Requirement | Minimum | |-------------|---------| | PHP | 8.2 or higher | | WHMCS | 9.x or higher | | ionCube Loader | v13 or newer (v14, v15) | ### Older module versions for WHMCS 8 - PHP 7.4: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php74/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php74/) - PHP 8.1: [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php81/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php81/) > To install and update a module, you must perform one and the same action. --- ## Step 1 — Download ```bash wget http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/php82/PUQ_WHMCS-MinIO-S3-latest.zip ``` All versions available via: [http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/](http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/) --- ## Step 2 — Extract ```bash unzip PUQ_WHMCS-MinIO-S3-latest.zip ``` --- ## Step 3 — Deploy Copy and replace the `puqMinIOS3` directory from `PUQ_WHMCS-MinIO-S3` to `WHMCS_WEB_DIR/modules/servers/` --- ## Step 4 — Server Configuration Create a new MinIO S3 server in WHMCS: Navigate to: **System Settings → Products/Services → Servers** 1. Click **Add New Server** 2. Enter the correct **Name** and **Hostname** 3. In the **Server Details** section, select the **PUQ MinIO S3** module and enter the correct username and password for the MinIO web interface 4. Click the **Test connection** button to verify ![Add server - General settings](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-wy9xeyds.png) ![Add server - Module settings](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-qirbrme5.png) --- ## Step 5 — Create Product Navigate to: **System Settings → Products/Services → Create a New Product** In the **Module Settings** section, select the **PUQ MinIO S3** module and configure the product options. ![WHMCS setup](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-wy9xeyds.png) # Email Template (puqMinIOS3 Notification disk limit) Create an email template for customer notifications when disk usage approaches the limit. Navigate to: **System Settings → Email Templates → Create New Email Template** --- ## Template configuration | Parameter | Value | |-----------|-------| | **Email Type** | Product/service | | **Unique Name** | `puqMinIOS3 Notification disk limit` | --- ## Email Subject ``` Disk space usage {$disk_used_percentage} % - {$username} ``` --- ## Email Body ```html Dear {$client_name}, This letter informs you that the disk space usage limit is coming to an end. Product/Service: {$service_product_name} Due Date: {$service_next_due_date} Username: {$username} Disk limit: {$disk_limit_bytes*$unit_coefficient} {$unit} Disk used: {$disk_used_unit} {$unit} ({$disk_used_percentage} %) Disk free: {$disk_free_unit} {$unit} ({$disk_free_percentage} %) {$signature} ``` --- ## Available template variables | Variable | Description | |----------|-------------| | `{$username}` | MinIO S3 account username | | `{$disk_limit_bytes*$unit_coefficient}` | Total disk space limit | | `{$disk_used_unit}` | Used disk space | | `{$disk_free_unit}` | Free disk space | | `{$disk_used_percentage}` | Used disk space percentage | | `{$disk_free_percentage}` | Free disk space percentage | | `{$unit}` | Disk space unit (MB, GB, TB, PB) | > **Note:** Standard WHMCS merge fields are also available in this template. ![Email template creation](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-qstyj3ql.png) ![Email template configuration](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-4lmh6j3t.png) # Email Template (puqMinIOS3 service Suspension Notification disk limit) Create an email template for customer notifications when the S3 account is suspended due to exceeding the disk limit. Navigate to: **System Settings → Email Templates → Create New Email Template** --- ## Template configuration | Parameter | Value | |-----------|-------| | **Email Type** | Product/service | | **Unique Name** | `puqMinIOS3 service Suspension Notification disk limit` | --- ## Email Subject ``` Suspension Information - {$username} ``` --- ## Email Body ```html Dear {$client_name}, This email informs you that the S3 account has been disabled due to running out of free space. It is also possible to upgrade to a package with more space. Product/Service: {$service_product_name} Due Date: {$service_next_due_date} Username: {$username} Disk limit: {$disk_limit_bytes*$unit_coefficient} {$unit} Disk used: {$disk_used_unit} {$unit} ({$disk_used_percentage} %) Disk free: {$disk_free_unit} {$unit} ({$disk_free_percentage} %) {$signature} ``` --- ## Available template variables | Variable | Description | |----------|-------------| | `{$username}` | MinIO S3 account username | | `{$disk_limit_bytes*$unit_coefficient}` | Total disk space limit | | `{$disk_used_unit}` | Used disk space | | `{$disk_free_unit}` | Free disk space | | `{$disk_used_percentage}` | Used disk space percentage | | `{$disk_free_percentage}` | Free disk space percentage | | `{$unit}` | Disk space unit (MB, GB, TB, PB) | > **Note:** Standard WHMCS merge fields are also available in this template. ![Email template creation](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-r0h0h8cr.png) ![Email template configuration](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-z5wp0k7c.png) # Add server (MinIO S3) ## Add a new server to the system WHMCS Navigate to: **System Settings → Servers → Add New Server** --- ## Step 1 — General settings Enter the correct **Name** and **Hostname** for your MinIO S3 server. ![Add server - General settings](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-1qscjxwt.png) --- ## Step 2 — Module settings In the **Server Details** section: 1. Select the **PUQ MinIO S3** module 2. Enter the correct **username** and **password** for the MinIO web interface 3. Click the **Test connection** button to verify the connection ![Add server - Module settings](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-3vexntjc.png) > **Note:** The MinIO user must have administrator privileges to manage users, policies, and buckets via the API. # Product Configuration ## Add new product to WHMCS Navigate to: **System Settings → Products/Services → Create a New Product** In the **Module Settings** section, select the **PUQ MinIO S3** module. --- ## Configuration parameters | Parameter | Description | |-----------|-------------| | **License key** | A pre-purchased license key for the PUQ MinIO S3 module. For the module to work correctly, the key must be active | | **Unit** | Packet disk space units (MB, GB, TB, PB) | | **Disk space size** | Disk size in this product (set to 0 for unlimited) | | **Notification disk limit email template** | Email template that will be sent when the disk quota is exceeded in % | | **Notification, used disk space X %** | Sets a percentage parameter (1-100, default 90), after exceeding this parameter a notification will be sent to the user | | **Group** | The group that will be assigned to the user on the server side of the MinIO S3 | | **Raw Policy** | The policy that is assigned to the user during creation on the server | | **Suspend exceeding disk limit email template** | The template of the letter that will be sent to the client if his disk limit is 100% or less 100% | | **Raw policy Disk limit** | The policy that will be applied to the client when the client runs out of space | | **Save usage history (days)** | The number of days it takes to save user disk usage statistics | | **Link to instruction** | Link to the instruction, if filled out, it will be reflected in the client area | | **Default Bucket** | Options to enable or disable the creation of a default bucket, and also set its prefix | | **Client Area** | Client zone settings — show or not show the password in the client zone, type how to show the password | --- ## Username rule Default: `{client_id}-{service_id}` | Macro | Description | |-------|-------------| | `{client_id}` | Client ID | | `{service_id}` | Service ID | | `{unixtime}` | Current Unix timestamp | | `{date}` | Current date (YYYY-MM-DD) | | `{time}` | Current time (HH-MM-SS) | | `{random_digit_x}` | Random digit string of length x | | `{random_letter_x}` | Random letter string of length x | --- ## Password rule Default: `12:123456789QAZWSXEDCRFVTGBYHNUJMIKqazwsxedcrfvtgbyhnujmikolp` Format: `length:charset` — where length is the password length and charset is the set of characters to use. --- ## Raw Policy (Standard) The policy that is assigned to the user during creation on the server: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "admin:Heal", "admin:SetBucketTarget", "admin:TopLocksInfo", "admin:DataUsageInfo", "admin:GetBucketQuota", "admin:GetBucketTarget" ], "Resource": [ "arn:aws:s3:::*" ] }, { "Effect": "Allow", "Action": [ "s3:*" ], "Resource": [ "arn:aws:s3:::*" ] } ] } ``` --- ## Raw Policy Disk Limit The policy that will be applied to the client when the client runs out of space: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "admin:Heal", "admin:SetBucketTarget", "admin:TopLocksInfo", "admin:DataUsageInfo", "admin:GetBucketQuota", "admin:GetBucketTarget" ], "Resource": [ "arn:aws:s3:::*" ] }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:DeleteObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::*" ] } ] } ``` > **Important:** Policy recalculation occurs once a day during the collection of server statistics (UpdateServerUsage). ![Product configuration](https://doc.puq.info/uploads/images/gallery/2026-03/embedded-image-lga4zu6v.png)