Portainer Docker Containers For WHMCS

About Portainer Docker Containers For WHMCS

Portainer Docker Containers For WHMCS is a module that connects your WHMCS system with Portainer, allowing you to sell and manage Docker containers just like traditional hosting products. It automates the deployment process, so containers are created, configured, and assigned to clients instantly upon purchase. Clients can control their containers directly from the WHMCS client area, including start, stop, restart actions, viewing logs, accessing the console, and more. You can also enable "App Templates" to let clients reinstall their stack using predefined configurations. Note: The module does not modify or manage the Docker configuration on your server. All aspects of host and container security remain the responsibility of the server administrator. For best practices and security guidelines, we recommend reviewing the OWASP Docker Security Cheat Sheet.

• Admin Area Features:

✔ Create/Suspend/Unsuspend/Terminate Container, Stack Or Swarm-Based Service

✔ Change Package

✔ Start/Stop/Restart/Recreate Service

✔ View Service Status And Details

✔ View Containers Assigned To Stack

✔ View Published Ports

✔ View Environment Variables

✔ View Container Logs

✔ View, Manage And Show Details Of Action Logs

✔ View Statistic Graphs:

✔ Memory

✔ CPU Usage

✔ Network Usage

✔ Disk I/O Usage

✔ Configure Product Details:

✔ Provide Product General Configuration:

✔ Define Default Instance Name

✔ Define Default Username

✔ Toggle Opening Container Console In New Window

✔ Assign Container Network

✔ Select Runtime Type

✔ Enable Privileged Mode

✔ Provide Docker-in-Docker Configuration:

✔ Enable Docker-in-Docker Functionality

✔ Enable Privileged Mode

✔ Select Runtime Type

✔ Define Default Docker Node Name

✔ Assign Container Network

✔ Provide App Templates Configuration:

✔ Select Default Application Groups

✔ Select Default Application

✔ Define Container Limits:

✔ Memory Reservation [MB]

✔ Memory Limit [MB]

✔ CPU Limit [Cores]

✔ Volume Size [GiB]

✔ Choose Features Available In Client Area:

✔ Select Available Container Details

✔ Select Available Stack Details

✔ Start/Stop/Restart/Recreate Service

✔ Reinstallation

✔ Environment Variables

✔ Published Ports

✔ Container Logs

✔ Console

✔ Graphs

✔ Assigned Containers

✔ Action Logs

✔ Choose Features Available In Admin Area:

✔ Service Actions

✔ Stack Details

✔ Assigned Containers

✔ Container Details

✔ Published Ports

✔ Environment Variables

✔ Container Logs

✔ Graphs

✔ Action Logs

✔ Generate Configurable Options

✔ Configure WHMCS Server Details For Selected Environment

• Addon Module Features:

✔ View Dashboard With List Of Launched Services

✔ Configure App Templates:

✔ Container Applications

✔ Stack Applications

✔ Swarm Applications

✔ Custom Applications

✔ Customize Application Details And Logo Images

✔ Create Application Groups And Assign App Templates

✔ Manage Media Library With Logotypes For App Templates

✔ Customize Module Language Files With "Translations" Tool

✔ View And Manage Logs

✔ View Queue Of Scheduled Tasks

• Client Area Features:

✔ View Container/Stack Status And Details

✔ Start/Stop/Restart/Recreate Service

✔ View Containers Assigned To Stack

✔ View Published Ports

✔ View Environment Variables

✔ View Action Logs

✔ Reinstall Service With Predefined Templates:

✔ Container Applications

✔ Stack Applications

✔ Swarm Applications

✔ Custom Applications

✔ View Container Logs

✔ Access Console

✔ View Container Graphs:

✔ Memory Usage

✔ CPU Usage

✔ Network Usage

✔ Disk I/O Usage

• Configurable Options:

✔ Application

✔ Memory Reservation

✔ Memory Limit

✔ CPU Limit

✔ Volume Size

• General Info:

✔ Requires Portainer Business Edition (BE)

✔ Supports Docker Labels For Domain Routing Via Traefik

✔ Multi-Language Support With Custom Translations Tool

✔ Supports PHP 8.3 Back To PHP 8.1

✔ Supports WHMCS V8.13 Back To WHMCS V8.10

✔ Requires ionCube Loader V14 Or Later

✔ Easy Module Upgrade To Open Source Version

Installation And Configuration

This tutorial will show you how to successfully install and configure Portainer Docker Containers For WHMCS. We will guide you step by step through the whole installation and configuration process.

1. Log in to our client area and download the module.

2. Extract the package and upload its content into the main WHMCS directory. The content of the package to upload should look like this.

3. When you install Portainer Docker Containers For WHMCS for the first time you have to rename 'license_RENAME.php' file. The file is located in 'modules/servers/PortainerDockerContainers/license_RENAME.php'. Rename it from 'license_RENAME.php' to 'license.php'.

4. In order to configure your license key, you have to edit the previously renamed 'license.php' file. Enter your license key between quotation marks as presented on the following screen. You can find your license key in our client area → 'My Products'.

5. Now, set up the 'storage' folder as recursively writable. This folder is available at '/yourWHMCS/modules/addons/PortainerDockerContainers/'. Note: It is needed for the Media Library to store uploaded images safely.

Addon Activation

6. Now you have to activate the module in your WHMCS system. Log in to your WHMCS admin area. Go to 'System Settings' → 'Addon Modules'. Afterwards, find 'Portainer Docker Containers' and press the 'Activate' button.

7. In the next step, you need to permit access to this module. To do so, click on the 'Configure' button, tick 'Full Administrator' and press 'Save Changes'.

8. You have just successfully installed Portainer Docker Containers For WHMCS! You can access your module under 'Addons' → 'Portainer Docker Containers'. Read the guide provided in the 'App Templates' or continue with this documentation.

Configuration of Server

9. Now, log in to your WHMCS and proceed to 'System Settings' → 'Servers' and press 'Add New Server'.

10. Fill in the Name, provide the Hostname or IP Address in both fields at the top (filling in both Hostname and IP Address fields is required to proceed). In the Server Details section: Set Module to 'Portainer Docker Containers' Access Key ID / Username - this field can be skipped. Enter your Secret Access Key / Password - use an admin API key. Click Test Connection to ensure proper communication with the Portainer instance. Click the Configure button to select your desired environment (Portainer endpoint). Note: The environment defines all core settings, such as available resources (CPU, RAM, GPU) and what container or stack templates will be used. These are configured directly in Portainer. In the WHMCS module, you only choose from existing environments. After selecting the environment, the Access Hash will be filled in automatically. If your Portainer server uses SSL, ensure the Secure' checkbox is enabled. You can also enable the Override with Custom Port option and enter your custom Portainer API port. Finally, adjust SSO Access Control if needed, then click Save Changes.

When you have multiple Portainer server connections created, it is important to mark one of them as default with an asterisk; otherwise, some issues may occur during further configuration.

11. It is time to create a server group. To do so, click on 'Create Server Group'.

12. Enter a name, click on your previously created server, press 'Add' and afterward 'Save Changes'.

Configuration of Product

13. In order to create and configure a product, go to 'System Settings' → 'Products/Services'. Click on 'Create a New Group' .

14. Enter a product group name and press 'Save Changes'.

15. When you have a product group, you can create your product. To create a product click on 'Create a New Product' .

16. Afterward, choose your product group, module and type from the dropdown menus, enter your product name and press 'Continue'. 'Product Type' should be set to 'Shared Hosting'.

App Templates

Before continuing to the product's settings, you must ensure you have at least one application or group of applications ready to use. Proceed to the addon module → App Templates section and follow below instruction to create a ready application that will be installed by default on the server. The App Templates section allows you to manage Docker-based applications that clients can deploy to their containers or stacks directly from the client area. Templates are divided into four types, available under separate tabs: Container Applications, Stack Applications, Swarm and Custom Applications. Use the interface to import, edit, group, and assign application templates to products.

Applications

This section allows you to load available templates from your connected Portainer environment and manage them within WHMCS. Switch between available categories: Container Applications, Stack Applications and Swarm Applications using the tabs at the top. Click the refresh icon to import or update the list of templates from Portainer. Custom Applications tab includes your templates created manually.

Once templates are imported, you can use action buttons to edit, duplicate, or delete them. Mass actions are also available for bulk management.

Groups

With the templates ready, all that is left is to gather them into groups and include said groups into products. Navigate to 'App Templates' → 'Groups' and click on the 'Create' button.

Read the information, then provide the group with: Name Description Items to include

You can use the action button and the mass action function to edit and delete template groups.

Your basic configuration of App Templates is now ready. For more advanced configuration, manual creation guides please refer to App Templates Advanced Configuration section in this documentation. For now, go back to your product's module settings and complete the configuration there.

Module Settings

17. Now, go to the 'Module Settings' section, choose your previously created server group from the dropdown menu. The module should automatically save and reload settings. If not, click on 'Save Changes' manually.

18. Proceed to 'Configuration' section and adjust the following: Default Instance Name - Enter the default name to be used when creating a new stack or container. The name must contain only lowercase letters, digits, hyphens (-), or underscores (_). Available variables: {$domain}, {$client.id}, {$service.id}, {$order.id}, {$random}. If left empty, the domain name will be used. Default Username - Enter the default username to be used when creating a new user. Available variables: {$domain}, {$client.id}, {$service.id}, {$order.id}, {$random}. If left empty, the domain name will be used. Open Container Console in New Window - Enable this option to open the container console in a new window when the feature is available in the client area. Container Network - Choose the network for container communication between services and with the external environment. Runtime Type - Select the OCI runtime to be used when starting the container. You can learn more about altenravie runtime types in the described use case. Privileged Mode - Run the container with full host privileges. Not recommended unless necessary.

Alternatively, to configure Docker-in-Docker (DinD), you also need to set up its configuration Enable Docker-in-Docker - Enable this option to run Docker inside a dedicated container for isolated client environments. When enabled, each service receives its own Docker-in-Docker container with an automatically installed Portainer Agent. This agent registers a separate node in Portainer, allowing the client’s containers or stacks to run independently from the host system. Runtime Type - Select the OCI runtime to be used when starting the Docker-in-Docker container (default: runc).<br/? Learn more about runtime types in the described use case. Container Network - Choose the network for the DinD container. The default value is bridge. Other networks may work, but on most systems only the default bridge network is supported. Privileged Mode - Run the container with full host privileges. Not recommended unless necessary. Docker Node Name - Define the template used to name and register the Portainer node for this DinD container (e.g. docker-in-docker-node-{$client.id}-{$service.id}). Find more detailed information on Docker-in-Docker feature in dedicated section.

19. Proceed with 'App Template Configuration'. App Templates Configuration - To create instances based on stack or container applications, you must first configure the App Templates in the module's addon. Once your applications and groups are set up there, you can select the desired application in the product's Module Settings tab to be used during instance creation. Please refer to the App Templates and App Templates Advanced Configuration sections of the documentation for detailed setup instructions. Default Application Group - The groups of applications available for reinstalls. See the Groups section for more details. Default Application - The application that will be installed by default during container or stack creation. See the Applications section. Note that if applications are downloaded from the server, they will be divided into two categories: Container Applications and Stack Applications. Make sure to choose the default application based on the type of product you are configuring.

20. Set up 'Container Limits': Memory Reservation [MB] - Specify the amount of memory (in MB) reserved for the container. Set to 0 for no reservation. Memory Limit [MB] - Set the maximum amount of memory (in MB) the container can use. Use 0 for unlimited. CPU Limit [Cores] - Set the maximum number of CPU cores available to the container. Use 0 for unlimited. Volume Size [GiB] - Set the container volume size in GiB. This feature requires the Docker overlay2 driver with quota support. Use 0 to skip limiting; yet this solution is not recommended because it allows unlimited disk usage and may expose other containers' volumes if shared mounts are used. Alternatively, you can use configurable options to allow clients to define these limits at checkout.

21. Next, select the features that will be available in the client area: Container Details - Show basic information about the container, such as status, IP address, and resource usage. Stack Details - Display information related to the assigned stack configuration. Start - Allow clients to start their container. Stop - Allow clients to stop their container. Restart - Allow clients to restart their container. Recreate - Allow clients to recreate their container, preserving the settings; volumes are preserved while data inside the container is reset. Reinstallation - Enable access to predefined application templates for quick reinstall. Environment Variables - Allow clients to view or manage container environment variables. Published Ports - Show mapped ports between the host and the container. Container Logs - Provide access to real-time container logs. Console - Allow access to the container's interactive console. Graph - Show performance graphs such as CPU, memory, and network usage. Assigned Containers - Display a list of all containers assigned to the client. Action Logs - Provide a history of actions performed on the container (e.g. start, stop, reinstall).

22. Select the features that will be available in the admin area. These options define what information and controls admins will see within the WHMCS service management page: Service Actions - Perform start, stop, or restart actions directly from the admin area. Stack Details - View the full configuration and status of the assigned stack. Assigned Containers - Display all containers linked to the service. Container Details - Show detailed information about the container, such as IP address, image, and resource usage. Published Ports - View the port mappings for the container. Environment Variables - View environment variables set for the container. Container Logs - Access logs generated by the container. Graphs - Display real-time resource usage graphs (CPU, RAM, network, disk I/O) per container. Action Logs - Review all actions performed on the container or stack from within WHMCS.

23. At the end of the configuration process, you can decide whether to generate configurable options for the product. Configurable options allow clients to customize container parameters individually during the order process. If no configurable options are defined, the fixed values set in the product configuration will be used instead. Available Configurable Options: app – Application memory_reservation – Memory Reservation memory_limit – Memory Limit max_cpu_usage – CPU Limit volume_size – Volume Size

Your product configuration is now complete. Do not forget to save the changes once ready. Before adding it to your offer, make sure to set appropriate pricing. Create as many products as needed, each with different applications or feature sets, to tailor your offer perfectly.

Docker-in-Docker Workflow

When the Docker-in-Docker feature is enabled, the module automatically: Creates a new container based on the official docker:dind image. Installs and starts the Portainer Agent inside it. Registers this container as a new node in Portainer. Launches the selected application, container, or stack inside this isolated Docker-in-Docker environment. During Reinstall, the existing DinD container is removed and recreated. During Terminate, both the DinD container and its Portainer node are deleted. Suspend and Unsuspend actions remain unaffected. Important: The created Docker-in-Docker container is registered as a new Portainer node. Make sure your Portainer license allows for adding additional nodes without limitation.

Technical Notes: The DinD container extends the official docker:dind image by including the Portainer Agent. Example image configuration: FROM docker:dind RUN apk add --no-cache curl RUN curl -L https://downloads.portainer.io/portainer-agent-ce-static-linux-amd64.tar.gz \ | tar -xz -C /usr/local/bin \ && mv /usr/local/bin/portainer-agent /usr/local/bin/portainer-agent EXPOSE 9001 COPY start.sh /start.sh RUN chmod +x /start.sh ENTRYPOINT ["/start.sh"] Port 2375 - Docker API (DinD) Port 9001 - Portainer Agent Other ports - dynamically assigned for client applications

Security Notes: The module does not modify or manage the Docker configuration on your server. All aspects of host and container security remain the responsibility of the server administrator. Running Docker-in-Docker requires privileged containers and can expose the Docker API internally. For secure deployments, always use TLS when exposing the Docker API and follow official security guidelines.

Recommended Reading: Docker Docs: Protect the Docker Daemon Socket OWASP Docker Security Cheat Sheet

Compatibility Notes: Works with both Container and Stack types. Each Docker-in-Docker instance acts as a separate Portainer node. Traefik integration remains unchanged but works best when ports are mapped 1:1 between host and container. Random or mismatched port mappings may require manual configuration adjustments in Traefik.

Management

Portainer Docker Containers For WHMCS allows your clients to manage and monitor their Docker containers directly from the WHMCS client area. In this short guide, you'll learn about the module's key features and how to configure them for both client and admin use.

Module Addon

The module addon is the central place for all administrative setup and management. Here, you can register products supported by the module, manage Docker templates, and access various utilities such as the media library, translation manager, and module logs.

App Templates Advanced Configuration

Please see the App Templates for basic configuration, here, you will find instructions for advanced users on how to manually manage existing container, stack, and swarm application templates. Admins can manually edit applications, define their runtime behavior, set default values, and customize input fields in the "Setting Details" section. There is also an option to create your own Custom Applications, which appear in the dedicated tab.

Default Stack Configuration

When a stack application is created without a custom Docker Compose configuration (template_stack_file is left empty), the module uses the default templates from Portainer's official repository. This behavior relies on two built-in variables: repository_url - the base URL of the template repository (e.g. https://github.com/portainer/templates) repository_stack_file - the path to the specific Docker Compose file in the repo (e.g. stacks/wordpress/docker-compose.yml) These two values are automatically combined to form the full link to the stack definition: https://github.com/portainer/templates/blob/master/stacks/wordpress/docker-compose.yml

You can preview all default stack templates directly here. To customize the default stack, simply copy the Docker Compose content from the original URL and paste it into the template_stack_file field. Once that field is filled in, only your custom configuration will be used.

Setting a Default Terminal Command

In both stack and container application templates, you can configure a terminal_command value. This determines the default command executed when the client accesses the container’s console. Available values (based on Portainer console options): /bin/ash /bin/bash (default) /bin/dash /bin/sh If the default command is not compatible with the container image, you can override it by editing the terminal_command setting default value.

Using Environment Variables in Custom Templates

If you're using a custom Docker Compose config in the template_stack_file field, you can introduce dynamic environment variables. These are made available to the client so they can enter values during deployment. To ensure these are parsed correctly: Use variable names prefixed with ENV_, e.g., ENV_MYSQL_ROOT_PASSWORD - only variables with the ENV_ prefix will be visible to clients and substituted during deployment.

In the Compose file, use the {literal} tag around any variables to prevent parsing errors, like this: {literal}MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}{/literal} Important: Skipping the {literal} wrapper will cause the configuration parser to fail, blocking the stack from being created.

Traefik Labels in Container Applications

Portainer Docker Containers For WHMCS supports the Traefik reverse proxy to automatically expose deployed containers and stacks via domain-based routing. This is achieved using dynamic Docker labels set in the application template (Container Applications) or docker-compose.yml files (Stack Applications).

To configure Traefik for a container-based application, go to the App Templates → Applications tab in the addon module, edit your container application, and navigate to the labels setting details.

Add the following labels as individual settings. You can use Smarty variables like {$hosting.id} or {$hosting.domain} for dynamic route generation: traefik.enable=1 traefik.docker.network=bridge traefik.http.routers.service-{$hosting.id}.entrypoints=web traefik.http.routers.service-{$hosting.id}.rule=Host(`{$hosting.domain}`) traefik.http.routers.service-{$hosting.id}.service=service-{$hosting.id} traefik.http.services.service-{$hosting.id}.loadbalancer.server.port=80 The application will be deployed with these labels automatically. The placeholder variables will be parsed at runtime, ensuring correct values for each service. Important: Make sure that both the Traefik container and the newly created service are attached to the same Docker network (e.g., bridge) to ensure routing works as expected.

Traefik with Stack Applications

Stack-based applications can also be configured with Traefik by modifying the template_stack_file field in the App Template form.

You must supply a full and valid docker-compose.yml script with the required Traefik labels. Below is an example that exposes a WordPress stack through Traefik: version: '2' services: db: image: mysql:5.7 volumes: - db_data:/var/lib/mysql restart: always network_mode: bridge environment: MYSQL_ROOT_PASSWORD: {literal}${MYSQL_DATABASE_PASSWORD}{/literal} MYSQL_DATABASE: wordpress MYSQL_USER: wordpress MYSQL_PASSWORD: strongpassword ports: - "{$hosting.id}6:3306" wordpress: image: wordpress:latest network_mode: bridge ports: - "8{$hosting.id}:80" restart: always environment: WORDPRESS_DB_HOST: {$params.serverip}:{$hosting.id}6 WORDPRESS_DB_USER: wordpress WORDPRESS_DB_PASSWORD: strongpassword labels: traefik.enable: "true" traefik.docker.network: "bridge" traefik.http.routers.service-{$hosting.id}.entrypoints: "web" traefik.http.routers.service-{$hosting.id}.rule: "Host(`{$hosting.domain}`)" traefik.http.routers.service-{$hosting.id}.service: "service-{$hosting.id}" traefik.http.services.service-{$hosting.id}.loadbalancer.server.port: "80" volumes: db_data:

Media Library

The media library allows you to upload images for use elsewhere in the module by admins and clients. To upload a new picture, click on the 'Upload Image' button. Note: The icons used in the Media Library by default are provided by Simple Icons and are licensed under the CC0 1.0 Universal (Public Domain Dedication) license.

You can delete images one by one by clicking on them. To delete all images at once, use the additional action button.

Translations

Customizing language files is now extremely easy with the "Translations" tool that is now available directly in the addon. Its simple design makes managing various language file tweaks a smooth and efficient process. Use this built-in tool to prepare translations for the original English files. You can also add missing or custom elements and define dynamic translations for error messages to ensure that all output, whether visible to you or your clients, is fully user-friendly. For detailed instructions on how to use the tool, please refer to the dedicated article here.

Logs

The 'Logs' tab is where the module logs are stored. You can filter the module logs by type with the 'Show' buttons: Info Notice Error Critical Total All information on Logs can be found in the dedicated Logs article.

Queue

The "Queue" tool helps you track and manage the tasks created by the module. It allows you to view and interact with task details, including task IDs, statuses, and related items. You can filter tasks, execute actions like deleting or running tasks, and even use mass actions for bulk operations. For detailed guidance on using this tool, please refer to the dedicated article available here.

Dashboard

The 'Dashboard' provides information and statistics related to the functions of the module. Press "i" to see service details.

Admin Area

Stack-based product type view: Start/stop/restart the service See stack details See assigned to the stack containers Action logs (more details & remove options)

Container-based product type view: Start/stop/restart the service See container details List of published ports (IP Address, Private Port, Public Port) Environment Variables Container Logs Action Logs (more details & remove options) Container Usage Graphs: Memory Usage, CPU Usage, Network Usage and Disk I/O Usage

Ordering

Owing to configurable options, you are able to offer a product that your clients can tailor according to their needs. Additionally, you are able to set up pricing for each configurable option, which makes your offer even more competitive.

Importing Existing Container

In this section, you can find short instructions on how to connect one of your clients to your already existing container in the Portainer panel. Take the following steps to make sure that the process will be carried out properly. 1. Firstly, manually create an order for your customer in WHMCS. Choose a client and in the summary, view click on the ' Add New Order' button. Next, select a 'Product/Service' and press 'Submit Order' . What is important, do not perform the 'Create' action. The status has to remain as 'Pending' . More info about placing orders can be found here 2. Proceed to the newly created product's card in your admin area. Find the following empty field: Instance ID Instance Type User ID Username The above-mentioned information has to be consistent with the data in your Portainer panel. Now, complete this field as presented below. Important! Remember to make sure that the format of the provided data is compatible with the format supported by the module. You can preview it for another product of the module you have already created and enter it in a similar way. If you completed the required data, now change the status from 'Pending' to 'Active' and 'Save Changes'.

3. If the completed data is correct, after refreshing the page, you will see the attached container from Portainer. Important! Remember to manually add other missing parameters such as credentials, IP Addresses, configurable options, etc. so they match the parameters of the attached container.

Client Area

With Portainer Docker Containers For WHMCS, clients can fully manage their Docker containers and stacks directly from the WHMCS client area. They can view service information, monitor performance, execute key actions, and deploy applications, all without needing direct access to Portainer. Available features depend on the options enabled in the product configuration. Service Actions that can be performed on either stack or container based product type: start, stop, and restart

Stack View

Below, you can see what the product might look like for the client "Stack" type with assigned Containers. Service Actions that can be performed on Stack-based product: start, stop, and restart. Table with Stack Details with any essential stack information, including name, current status, and exposed environment variables. Table with Assigned Containers that includes a list of all containers associated with the client’s stack. Each entry includes the container name, status, image, IP address, and published ports. Clicking a container entry opens a detailed view with technical and performance data.

Container assigned to stack view. Clicking on a container from the stack view opens a dedicated detail panel with full technical insight. The view is divided into multiple sections for clarity and easier access to specific information. Use the same action buttons: Start, Stop, Restart, and Recreate directly within the container view. Service management options Container details Published ports - Mappings between private and public ports. Environment variables - All environment variables currently assigned to the container are displayed, including sensitive configuration data and service paths.

Swarm View

Users can effortlessly start, stop, or restart their containers using intuitive action buttons (Start, Stop, and Restart). Service management options Swarm stack details Assigned Containers

Container assigned to swarm stack view. Clicking on a container opens a dedicated detail panel with full technical insight. The view is divided into multiple sections for clarity and easier access to specific information. Use the same action buttons: Start, Stop, and Restart directly within the container view. Service management options Container details Published ports - Mappings between private and public ports. Environment variables - All environment variables currently assigned to the container are displayed, including sensitive configuration data and service paths.

Container View

Users can effortlessly start, stop, restart or recreate their containers using intuitive action buttons (Start, Stop,Restart, and Recreate). Service management options Container details Published ports Environment variables

Action Logs

The Action Logs section tracks all actions performed on the container or stack, such as starting, stopping, reinstallation, and template deployments. This information provides clients with a history of operations for their services.

Console

An integrated console available for clients to execute commands directly within their container's environment. The console can be opened directly in the WHMCS client area or in a separate tab.

Container Logs

Clients have access to detailed container logs.

Graphs

Real-time graphs display vital metrics such as CPU usage, memory consumption, disk I/O, and network activity, allowing clients to monitor their container's performance.

Reinstallation

Clients can reinstall their container or stack using predefined application templates, enhancing the process of resetting or changing their environment. Important: Reinstalling an application will permanently remove any existing container data.

If required, fill in any fields related to the selected application. Some templates may ask for additional parameters (e.g. database password), while others may not require any input. Once you are ready, confirm the action to proceed with reinstallation. Important: Reinstalling an application will permanently delete all existing container or stack data.

Use Cases

The following use cases illustrate practical examples of how Portainer Docker Containers For WHMCS can be extended and customized through App Templates, stack configurations, and product settings. Each scenario focuses on a real-world need, such as defining custom networks, overriding commands, attaching volumes, or using configurable options. Furthermore, it shows how these features can be applied to create flexible, isolated, and fully automated container environments for your clients.

Custom Networks In Stack Applicaions

Portainer Docker Containers For WHMCS allows defining custom proxy networks directly inside stack templates. This is useful when your application stack requires an internal network layer, for example, when using Traefik as a reverse proxy within the client’s isolated environment. Network definitions are added inside the template_stack_file field of an App Template. Each stack can create its own dedicated bridge network using dynamic variables such as proxy_{$hosting.id}, ensuring container isolation and predictable DNS-based service discovery inside the stack.

How to define a custom proxy network in a Stack Application: Navigate to: App Templates → Stacks Select the application you want to configure. In the template_stack_file field, define your docker-compose.yml. Include a custom network declaration and attach your services to that network. (Example below is not a full Docker Compose file; it focuses on showing the structure.)

Sample configuration using Traefik & custom proxy network: version: "3.9" networks: proxy_{$hosting.id}: name: proxy_{$hosting.id} driver: bridge volumes: db_data: services: traefik: image: "traefik:v3.3" command: - "--providers.docker=true" - "--providers.docker.exposedbydefault=false" - "--entryPoints.web.address=:80" ports: - "80:80" - "8080:8080" volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" networks: - proxy_{$hosting.id} restart: always labels: - traefik.enable=true - traefik.docker.network=proxy_{$hosting.id} db: image: mysql:5.7 restart: always networks: - proxy_{$hosting.id} volumes: - db_data:/var/lib/mysql environment: MYSQL_ROOT_PASSWORD: {literal}${MYSQL_DATABASE_PASSWORD}{/literal} MYSQL_DATABASE: wordpress MYSQL_USER: wordpress MYSQL_PASSWORD: strongpassword wordpress: image: wordpress:latest restart: always networks: - proxy_{$hosting.id} environment: WORDPRESS_DB_HOST: db:3306 WORDPRESS_DB_USER: wordpress WORDPRESS_DB_PASSWORD: strongpassword WORDPRESS_DB_NAME: wordpress labels: - traefik.enable=true - traefik.docker.network=proxy_{$hosting.id} - traefik.http.routers.wp-{$hosting.id}.entrypoints=web - traefik.http.routers.wp-{$hosting.id}.rule=Host(`{$hosting.domain}`) - traefik.http.routers.wp-{$hosting.id}.service=wp-{$hosting.id} - traefik.http.services.wp-{$hosting.id}.loadbalancer.server.port=80

Notes: Every stack may define its own internal bridge network such as proxy_{$hosting.id}. These networks are removed automatically when the stack is terminated. Traefik and application containers communicate through the internal proxy network. Routing is based on labels and domain rules, no need to expose additional ports to the public network. This setup is well-suited for isolated, self-contained applications where each stack includes its own reverse proxy layer (e.g. Traefik).

Customizing Commands, Ports, And Images In Application Templates

This use case applies when a provider needs full control over how an application container is executed. Some images require additional runtime parameters (e.g., CLI flags, passwords, startup scripts), custom port definitions, or even a completely different image tag than the one defined in Portainer. The module allows you to override three key runtime attributes directly in an App Template: container_command - custom CMD instruction for the container (e.g., bash my-script.sh {$service.id}) container_ports - custom list of container ports (e.g., ["80/tcp","443/tcp"]) container_image - override the image and tag (e.g., nginx:latest) These options enable fine-tuned deployments when the default Portainer template settings are insufficient. All values are configured per application in the App Templates section, and the module automatically applies them during container creation or reinstall.

Defining Custom Volumes For Container Templates

This use case shows how providers can attach custom volumes (both bind and local) to containers created through App Templates. The module introduces the container_volumes configuration field, allowing you to map host paths to container directories and control read-only or read-write access.

How to define volumes in an App Template Go to: App Templates → Applications Open the selected application Edit the container_volumes field; create it if it does not exist Provide a JSON list of volume objects using Smarty-safe tags {ldelim} and {rdelim}

JSON Structure Each volume object contains: bind - path on the host (or null to allow Docker to assign a local volume) container - path inside the container readonly - true for read-only, false for read-write

Example configuration: [ {ldelim} "bind": null, "container": "/etc/nginx", "readonly": true {rdelim}, {ldelim} "bind": null, "container": "/usr/share/nginx/html", "readonly": false {rdelim}, {ldelim} "bind": "/opt/nginx/logs{$service.id}", "container": "/var/log/nginx", "readonly": false {rdelim} ]

Example explained (Nginx): /etc/nginx is mounted as read-only /usr/share/nginx/html is mounted as read-write /var/log/nginx stores logs in a customer-specific directory on the host: /opt/nginx/logs{$service.id} Volumes displayed in Portainer may include automatically generated Docker volume IDs or bind paths, depending on configuration.

Overriding Default Container Username

This use case explains how to define a custom user for the built-in container terminal. By default, Portainer executes terminal sessions as root. The module allows overriding this behavior by defining a terminal_user value in an App Template. This is useful when: root access is not desired, the application requires running commands as a specific user (e.g., www-data for WordPress), the image defines multiple system users, and one of them should be used for security or compatibility reasons.

How to set a custom terminal user Go to: App Templates → Applications Open the application you want to modify Add or edit the terminal_user setting Enter a username that exists inside the Docker image (e.g., www-data, node, postgres, or a numeric uid / uid:gid pair)

Accepted formats The terminal user must match one of the following formats: user user:group uid uid:gid Portainer will reject values that do not exist in /etc/passwd inside the container.

Behavior on deployment & reinstall If terminal_user is defined → the module uses it for the terminal session If not defined → the user defaults to root During reinstall, the correct terminal user is restored automatically (stored in WHMCS custom fields for persistence)

Example: WordPress container terminal To run terminal commands as the web server user instead of root, define: terminal_user = www-data This prevents errors such as: unable to find user rootXXXXX: no matching entries in passwd file which occurs when a non-existent user is set.

Using Configurable Options Inside Stack Applications

This use case describes how to use WHMCS Configurable Options (CO) as dynamic values inside stack templates. This allows providers to pass user-selected parameters—such as disk size, limits, GPU flags, memory settings, and so on - directly into Docker Compose YAML, labels, or environment variables during stack creation. Configurable Options become available inside App Template fields using the {$params.configoptions.*} variable.

How to use Configurable Options inside a stack Create or edit a WHMCS Configurable Options Group (e.g., Disk Size, CPU Limit, Memory Limit). Assign these options to your product that uses Portainer Docker Containers. Go to: App Templates → Applications → Application details. Edit the field where you want to use the value (e.g., labels, template_stack_file, environment, etc.). Insert the CO variable using: {$params.configoptions.option_name} The module automatically injects the current value when creating or reinstalling the service.

Example: Passing "Disk Size" from WHMCS to container labels If you defined a Configurable Option: disk_size = 15 MB Then inside the App Template → labels field you can use: traefik.enable=1 traefik.docker.network=bridge disk_customoption={$params.configoptions.disk_size} During service creation, this will appear in Portainer as: disk_customoption = 15

Example inside docker-compose (template_stack_file) You can also use CO values inside stack compose files: version: "3.9" services: app: image: ubuntu:latest environment: DISK_SIZE: "{$params.configoptions.disk_size}" labels: - "disk.size={$params.configoptions.disk_size}"

Improving Container Security Using Alternative Runtimes

This use case shows how container isolation can be improved by using an alternative container runtime instead of the default one. The module allows administrators to choose the runtime used to start containers, which helps limit container privileges. To select a different runtime, open the product module settings and choose the Runtime option in either the Configuration or Docker-in-Docker Configuration section.

Example: Using Sysbox Runtime One example of an alternative runtime is Sysbox. Sysbox improves container isolation by: using Linux user namespaces (container root has no host privileges), hiding host system details inside the container, virtualizing selected parts of procfs and sysfs, locking initial container mounts.

Running System-Level Software Sysbox also allows containers to run system-level software that normally requires elevated privileges, such as: systemd Docker and Docker-in-Docker Kubernetes / K3s buildx (including multi-architecture builds) These workloads can run without privileged containers or special images.

Important Notes Alternative runtimes can improve container separation compared to the default runtime. When Docker-in-Docker is used together with Sysbox, Privileged Mode is not required. The module does not install or manage container runtimes on the host, the selected runtime must be installed and maintained by the server administrator.

Tips

1. If any technical or unclear environment variables are visible to clients, you can easily make them more user-friendly using the Translations tool. Take a moment to review the Translations Tool documentation and its Missing Elements section to ensure all custom lines are properly translated.

Update Instructions

An essential guidance through the process of updating the module is offered here. Ensure successful completion of the module update by carefully following each step, thereby preventing data loss or any unforeseen issues. Additionally, you will find a current list of supplementary actions necessary for a smooth update process there.

Upgrade Guide

Seeking a solution that offers greater flexibility, customization tailored to your precise needs, and unrestricted availability? There is an option that not only proves to be cost-effective in the long run but also includes prioritized support services, making it a truly valuable investment. Opt for the Open Source version of your Portainer Docker Containers For WHMCS module to unlock these benefits. Simply click on either the Get Source Code or Upgrade To Lifetime button found on the product's page in our client area to complete the one-step upgrade process, with a dedicated discount already applied. Follow a comprehensive guide covering the transition process, the advantages it brings, and step-by-step instructions on what to do next after the order has been successfully finalized.

Common Problems

1. When you have problems with connection, check whether your SELinux or firewall does not block ports.