# 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 Installation and Update ### MinIO S3 module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/whmcs-module-minio-s3.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/) | [Community](https://community.puqcloud.com/) ## System requirements | Requirement | Minimum / Supported Version | |-------------|----------------------------| | **WHMCS** | 8.x+, 9.x+. | | **PHP** | 7.4, 8.1, 8.2, 8.3, 8.4 | | **ionCube Loader** | v15+ | | **MinIO Server** | `RELEASE.2025-04-22T22:12:26Z` or lower | > [!IMPORTANT] > **MinIO Server Version:** The module works exclusively with MinIO server version **`RELEASE.2025-04-22T22:12:26Z`** or lower. Versions newer than this release are not supported. > > **ionCube Loader:** The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server. --- ## Download > **Note:** The module now uses **ionCube 15**, which provides universal out-of-the-box support for all encodings across modern PHP runtimes. > > All versions can be found at this link: > [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/) > > Older module versions for WHMCS 8 are available in the archive directory: > [https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/archive/](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/archive/) 1. Download the latest version of the module directly to your server: ```bash wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/PUQ_WHMCS-MinIO-S3-latest.zip ``` 2. Unzip the archive: ```bash unzip PUQ_WHMCS-MinIO-S3-latest.zip ``` --- ## Installation ### Upload files Copy the `puqMinIOS3` directory from the extracted archive to the WHMCS servers module directory: ```bash cp -r puqMinIOS3 /path/to/whmcs/modules/servers/ ``` Or target path: ``` WHMCS_WEB_DIR/modules/servers/puqMinIOS3 ``` Once the files are uploaded, proceed to the configuration chapter to set up your server and product. --- ## Update The update procedure is the same as installation — replace the existing files with the new version: 1. Download the latest version as described in the Download section. 2. Unzip the archive. 3. Replace the existing `WHMCS_WEB_DIR/modules/servers/puqMinIOS3` directory with the new one. 4. Verify the version number in the module interface matches the new release. # Setup guide: MinIO S3 setup ## Section 1 — Installing and configuring the MinIO server > [!IMPORTANT] > **Supported MinIO Version:** The module works exclusively with MinIO server version **`RELEASE.2025-04-22T22:12:26Z`** or lower. Update packages and download the compatible MinIO binary: ```bash sudo apt update # Download the supported release (RELEASE.2025-04-22T22-12-26Z): wget https://dl.min.io/server/minio/release/linux-amd64/archive/minio.RELEASE.2025-04-22T22-12-26Z -O 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-09/embedded-image-c09gevcv.png) *04-minio-setup.png* # Setup guide: WHMCS setup ### MinIO S3 module **[WHMCS](https://puqcloud.com/link.php?id=77)** ##### [Order now](https://puqcloud.com/whmcs-module-minio-s3.php) | [Download](https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-MinIO-S3/) | [Community](https://community.puqcloud.com/) --- ## Step 1 — Add server in WHMCS 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-09/embedded-image-witheva0.png) *05-add-server-1.png* ![Add server - Module settings](https://doc.puq.info/uploads/images/gallery/2026-09/embedded-image-jqs9znyx.png) *06-add-server-2.png* --- ## Step 2 — 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-09/embedded-image-witheva0.png) *05-add-server-1.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-09/embedded-image-umdkddhv.png) *07-email-template-1.png* ![Email template configuration](https://doc.puq.info/uploads/images/gallery/2026-09/embedded-image-t40c6vk6.png) *08-email-template-2.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-09/embedded-image-3lu5phym.png) *09-email-template-suspension-1.png* ![Email template configuration](https://doc.puq.info/uploads/images/gallery/2026-09/embedded-image-cug8ocs0.png) *10-email-template-suspension-2.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-09/embedded-image-1s55x4ov.png) *05-add-server-1.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-09/embedded-image-jew8kk49.png) *06-add-server-2.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-09/embedded-image-axuefvgz.png) *11-product-configuration.png*