Portainer Docker Containers For WHMCS
(→Module Settings) |
|||
| (14 intermediate revisions by one user not shown) | |||
| Line 1: | Line 1: | ||
<meta name="keywords" content="portainer docker containers for whmcs, whmcs portainer docker containers configuration, whmcs portainer docker containers management, whmcs portainer docker containers installation, whmcs portainer docker containers common problems, about whmcs portainer docker containers, whmcs sportainer docker containers documentation, whmcs portainer docker containers faq, whmcs portainer docker containers help, whmcs sportainer docker containers guide, whmcs portainer docker containers wiki, whmcs portainer docker containers tutorial, whmcs portainer docker containers tips"></meta> | <meta name="keywords" content="portainer docker containers for whmcs, whmcs portainer docker containers configuration, whmcs portainer docker containers management, whmcs portainer docker containers installation, whmcs portainer docker containers common problems, about whmcs portainer docker containers, whmcs sportainer docker containers documentation, whmcs portainer docker containers faq, whmcs portainer docker containers help, whmcs sportainer docker containers guide, whmcs portainer docker containers wiki, whmcs portainer docker containers tutorial, whmcs portainer docker containers tips"></meta> | ||
<meta name="description" content="ModulesGarden Wiki Contains All The Information You Need About The Portainer Docker Containers For WHMCS Module."></meta> | <meta name="description" content="ModulesGarden Wiki Contains All The Information You Need About The Portainer Docker Containers For WHMCS Module."></meta> | ||
| − | |||
| − | |||
| − | |||
=About [https://www.modulesgarden.com/products/whmcs/portainer-docker-containers Portainer Docker Containers For WHMCS]= | =About [https://www.modulesgarden.com/products/whmcs/portainer-docker-containers Portainer Docker Containers For WHMCS]= | ||
{| | {| | ||
|style="padding: 10px 0px 10px 0px;"|'''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.<br/> | |style="padding: 10px 0px 10px 0px;"|'''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.<br/> | ||
| − | It automates the deployment process, so containers are created, configured, and assigned to clients instantly upon purchase.<br/> Clients can control their containers directly from the WHMCS client area, including start, stop, restart actions, viewing logs, accessing the console, and more. <br/>You can also enable "App Templates" to let clients reinstall their stack using predefined configurations. | + | It automates the deployment process, so containers are created, configured, and assigned to clients instantly upon purchase.<br/> Clients can control their containers directly from the WHMCS client area, including start, stop, restart actions, viewing logs, accessing the console, and more. <br/>You can also enable "App Templates" to let clients reinstall their stack using predefined configurations. <br/> |
| + | |||
| + | '''''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.<br/> For best practices and security guidelines, we recommend reviewing the [https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html OWASP Docker Security Cheat Sheet].'' | ||
|} | |} | ||
*'''Admin Area Features:''' | *'''Admin Area Features:''' | ||
{| | {| | ||
| − | |style="padding: 10px 0px 0px 30px;"|✔ Create/Suspend/Unsuspend/Terminate Container | + | |style="padding: 10px 0px 0px 30px;"|✔ Create/Suspend/Unsuspend/Terminate Container, Stack Or Swarm-Based Service |
|} | |} | ||
{| | {| | ||
| Line 19: | Line 18: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 0px 30px;"|✔ Start/Stop/Restart Service | + | |style="padding: 0px 0px 0px 30px;"|✔ Start/Stop/Restart/Recreate Service |
|} | |} | ||
{| | {| | ||
| Line 70: | Line 69: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 0px | + | |style="padding: 0px 0px 0px 60px;"|✔ Assign Container Network |
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 0px 60px;"|✔ Select Default Application | + | |style="padding: 0px 0px 0px 60px;"|✔ Select Runtime Type |
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Enable Privileged Mode | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 45px;"|✔ Provide Docker-in-Docker Configuration: | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Enable Docker-in-Docker Functionality | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Enable Privileged Mode | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Select Runtime Type | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Define Default Docker Node Name | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Assign Container Network | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 45px;"|✔ Provide App Templates Configuration: | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Select Default Application Groups | ||
|} | |} | ||
{| | {| | ||
| Line 79: | Line 105: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 0px 45px;"|✔ Define Container Limits | + | |style="padding: 0px 0px 0px 45px;"|✔ Define Container Limits: |
|} | |} | ||
{| | {| | ||
| Line 89: | Line 115: | ||
{| | {| | ||
|style="padding: 0px 0px 0px 60px;"|✔ CPU Limit [Cores] | |style="padding: 0px 0px 0px 60px;"|✔ CPU Limit [Cores] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 60px;"|✔ Volume Size [GiB] | ||
|} | |} | ||
{| | {| | ||
| Line 100: | Line 129: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 0px 60px;"|✔ Start/Stop/Restart Service | + | |style="padding: 0px 0px 0px 60px;"|✔ Start/Stop/Restart/Recreate Service |
|} | |} | ||
{| | {| | ||
| Line 175: | Line 204: | ||
{| | {| | ||
|style="padding: 0px 0px 0px 45px;"|✔ Stack Applications | |style="padding: 0px 0px 0px 45px;"|✔ Stack Applications | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 45px;"|✔ Swarm Applications | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 45px;"|✔ Custom Applications | ||
|} | |} | ||
{| | {| | ||
| Line 189: | Line 224: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px | + | |style="padding: 0px 0px 0px 30px;"|✔ View And Manage Logs |
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 10px 30px;"|✔ View Queue Of Scheduled Tasks | ||
|} | |} | ||
| Line 197: | Line 235: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px 0px 30px;"|✔ Start/Stop/Restart Service | + | |style="padding: 0px 0px 0px 30px;"|✔ Start/Stop/Restart/Recreate Service |
|} | |} | ||
{| | {| | ||
| Line 219: | Line 257: | ||
{| | {| | ||
|style="padding: 0px 0px 0px 45px;"|✔ Stack Applications | |style="padding: 0px 0px 0px 45px;"|✔ Stack Applications | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 45px;"|✔ Swarm Applications | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 0px 45px;"|✔ Custom Applications | ||
|} | |} | ||
{| | {| | ||
| Line 253: | Line 297: | ||
|} | |} | ||
{| | {| | ||
| − | |style="padding: 0px 0px | + | |style="padding: 0px 0px 0px 30px;"|✔ CPU Limit |
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 10px 30px;"|✔ Volume Size | ||
|} | |} | ||
| Line 360: | Line 407: | ||
* After selecting the environment, the '''Access Hash''' will be filled in automatically. | * After selecting the environment, the '''Access Hash''' will be filled in automatically. | ||
* If your Portainer server uses SSL, ensure the '''Secure'''' checkbox is enabled. <br/>You can also enable the '''Override with Custom Port''' option and enter your custom Portainer API port. | * If your Portainer server uses SSL, ensure the '''Secure'''' checkbox is enabled. <br/>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'''. | + | * Finally, adjust '''SSO Access Control''' if needed, then click '''Save Changes'''. |
| − | + | ||
| − | + | ||
|} | |} | ||
{| | {| | ||
| Line 369: | Line 414: | ||
{| | {| | ||
|style="padding: 0px 0px 20px 25px;"|[[File:PDC_8_1.png]] | |style="padding: 0px 0px 20px 25px;"|[[File:PDC_8_1.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 15px;"|'''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.''' | ||
|} | |} | ||
{| | {| | ||
| Line 417: | Line 465: | ||
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.<br/> | 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.<br/> | ||
| − | Templates are divided into | + | Templates are divided into four types, available under separate tabs: '''Container Applications, Stack Applications, Swarm''' and '''Custom Applications'''.<br/> |
Use the interface to import, edit, group, and assign application templates to products. | Use the interface to import, edit, group, and assign application templates to products. | ||
|} | |} | ||
| Line 423: | Line 471: | ||
{| | {| | ||
|style="padding: 10px 0px 15px 15px;"|This section allows you to load available templates from your connected Portainer environment and manage them within WHMCS. <br/> | |style="padding: 10px 0px 15px 15px;"|This section allows you to load available templates from your connected Portainer environment and manage them within WHMCS. <br/> | ||
| − | * Switch between available categories: Container Applications | + | * 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. | * Click the refresh icon to import or update the list of templates from Portainer. | ||
| + | * Custom Applications tab includes your templates created manually. | ||
|} | |} | ||
{| | {| | ||
| Line 479: | Line 528: | ||
* '''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. | * '''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 [[#Improving_Container_Security_Using_Alternative_Runtimes|use case]]. | ||
| + | * '''Privileged Mode''' - Run the container with full host privileges. Not recommended unless necessary. | ||
|} | |} | ||
{| | {| | ||
|style="padding: 0px 0px 20px 25px;"|[[File:PDC_16.png]] | |style="padding: 0px 0px 20px 25px;"|[[File:PDC_16.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''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.<br/> When enabled, each service receives its own Docker-in-Docker container with an automatically installed '''Portainer Agent'''. <br/>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: <code>runc</code>).<br/? Learn more about runtime types in the described [[#Improving_Container_Security_Using_Alternative_Runtimes|use case]]. | ||
| + | * '''Container Network''' - Choose the network for the DinD container. The default value is <code>bridge</code>. Other networks may work, but on most systems only the default <code>bridge</code> 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. <code>docker-in-docker-node-{$client.id}-{$service.id}</code>).<br/> | ||
| + | |||
| + | Find more detailed information on Docker-in-Docker feature in [[#Docker-in-Docker_Workflow|dedicated section]]. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:PDC_16_0.png]] | ||
|} | |} | ||
{| | {| | ||
| Line 488: | Line 553: | ||
'''App Templates Configuration''' - To create instances based on stack or container applications, you must first configure the App Templates in the module's addon. <br/> 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. <br/> Please refer to the [[##App_Templates|App Templates]] and [[#App_Templates_Advanced_Configuration|App Templates Advanced Configuration]] sections of the documentation for detailed setup instructions. | '''App Templates Configuration''' - To create instances based on stack or container applications, you must first configure the App Templates in the module's addon. <br/> 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. <br/> Please refer to the [[##App_Templates|App Templates]] and [[#App_Templates_Advanced_Configuration|App Templates Advanced Configuration]] sections of the documentation for detailed setup instructions. | ||
| − | * '''Default Application Group''' - The | + | * '''Default Application Group''' - The groups of applications available for reinstalls. See the [[#Groups|Groups]] section for more details. |
* '''Default Application''' - The application that will be installed by default during container or stack creation. See the [[#Applications|Applications]] section.<br/> Note that if applications are downloaded from the server, they will be divided into two categories: '''Container Applications''' and '''Stack Applications'''.<br/> Make sure to choose the default application based on the type of product you are configuring. | * '''Default Application''' - The application that will be installed by default during container or stack creation. See the [[#Applications|Applications]] section.<br/> Note that if applications are downloaded from the server, they will be divided into two categories: '''Container Applications''' and '''Stack Applications'''.<br/> Make sure to choose the default application based on the type of product you are configuring. | ||
|} | |} | ||
| Line 498: | Line 563: | ||
* '''Memory Reservation [MB]''' - Specify the amount of memory (in MB) reserved for the container. Set to 0 for no reservation. | * '''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. | * '''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. | + | * '''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.<br/> 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.<br/> | |
Alternatively, you can use configurable options to allow clients to define these limits at checkout. | Alternatively, you can use configurable options to allow clients to define these limits at checkout. | ||
|} | |} | ||
| Line 511: | Line 576: | ||
* '''Start''' - Allow clients to start their container. | * '''Start''' - Allow clients to start their container. | ||
* '''Stop''' - Allow clients to stop their container. | * '''Stop''' - Allow clients to stop their container. | ||
| − | * '''Restart''' - Allow clients to restart 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. | * '''Reinstallation''' - Enable access to predefined application templates for quick reinstall. | ||
* '''Environment Variables''' - Allow clients to view or manage container environment variables. | * '''Environment Variables''' - Allow clients to view or manage container environment variables. | ||
| Line 551: | Line 617: | ||
* <code>memory_limit</code> – '''Memory Limit''' | * <code>memory_limit</code> – '''Memory Limit''' | ||
* <code>max_cpu_usage</code> – '''CPU Limit''' | * <code>max_cpu_usage</code> – '''CPU Limit''' | ||
| + | * <code>volume_size</code> – '''Volume Size''' | ||
|} | |} | ||
{| | {| | ||
| Line 564: | Line 631: | ||
{| | {| | ||
|style="padding: 0px 0px 30px 25px;"|[[File:PDC_21_1.png]] | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_21_1.png]] | ||
| + | |} | ||
| + | ====Docker-in-Docker Workflow==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"|When the '''Docker-in-Docker''' feature is enabled, the module automatically: | ||
| + | * Creates a new container based on the official <code>docker:dind</code> 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.<br/> | ||
| + | |||
| + | '''''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.'' | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''Technical Notes:''' <br/> | ||
| + | The DinD container extends the official <code>docker:dind</code> image by including the '''Portainer Agent'''.<br/> | ||
| + | Example image configuration: | ||
| + | <pre> | ||
| + | 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"] | ||
| + | </pre> | ||
| + | |||
| + | * Port <code>2375</code> - Docker API (DinD) | ||
| + | * Port <code>9001</code> - Portainer Agent | ||
| + | * Other ports - dynamically assigned for client applications | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''Security Notes:''' <br/> | ||
| + | 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.<br/> | ||
| + | Running Docker-in-Docker requires '''privileged containers''' and can expose the Docker API internally.<br/> | ||
| + | For secure deployments, always use TLS when exposing the Docker API and follow official security guidelines. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''Recommended Reading:''' | ||
| + | * [https://docs.docker.com/engine/security/protect-access/ Docker Docs: Protect the Docker Daemon Socket] | ||
| + | * [https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html OWASP Docker Security Cheat Sheet] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"|'''Compatibility Notes:''' <br/> | ||
| + | * 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. | ||
|} | |} | ||
| Line 578: | Line 694: | ||
===App Templates Advanced Configuration=== | ===App Templates Advanced Configuration=== | ||
{| | {| | ||
| − | |style="padding: 10px 0px 30px 15px;"|Please see the [[#App_Templates|App Templates]] for basic configuration, here you will find instructions for advanced users on how to manually manage existing container | + | |style="padding: 10px 0px 30px 15px;"|Please see the [[#App_Templates|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.<br/> |
| − | Admins can manually edit applications, define their runtime behavior, set default values, and customize input fields in the "Setting Details" section. | + | Admins can manually edit applications, define their runtime behavior, set default values, and customize input fields in the "Setting Details" section. <br/> |
| + | There is also an option to create your own Custom Applications, which appear in the dedicated tab. | ||
|} | |} | ||
| Line 599: | Line 716: | ||
|style="padding: 0px 0px 15px 15px;"|You can preview all default stack templates directly [https://github.com/portainer/templates here]. <br/> | |style="padding: 0px 0px 15px 15px;"|You can preview all default stack templates directly [https://github.com/portainer/templates here]. <br/> | ||
To customize the default stack, simply copy the Docker Compose content from the original URL and paste it into the <code>template_stack_file</code> field.<br/> Once that field is filled in, only your custom configuration will be used. | To customize the default stack, simply copy the Docker Compose content from the original URL and paste it into the <code>template_stack_file</code> field.<br/> Once that field is filled in, only your custom configuration will be used. | ||
| + | |} | ||
| + | |||
| + | ====Setting a Default Terminal Command==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"|In both stack and container application templates, you can configure a <code>terminal_command</code> value.<br/> This determines the default command executed when the client accesses the container’s console.<br/> | ||
| + | |||
| + | Available values (based on Portainer console options): | ||
| + | * <code>/bin/ash</code> | ||
| + | * <code>/bin/bash</code> ''(default)'' | ||
| + | * <code>/bin/dash</code> | ||
| + | * <code>/bin/sh</code> | ||
| + | |||
| + | If the default command is not compatible with the container image, you can override it by editing the <code>terminal_command</code> setting default value. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_44_1.png]] | ||
|} | |} | ||
| Line 619: | Line 752: | ||
{| | {| | ||
|style="padding: 0px 0px 30px 25px;"|[[File:PDC_44.png]] | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_44.png]] | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
|} | |} | ||
| Line 762: | Line 879: | ||
{| | {| | ||
|style="padding: 0px 0px 30px 25px;"|[[File:PDC_40.png]] | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_40.png]] | ||
| + | |} | ||
| + | |||
| + | ===[https://www.docs.modulesgarden.com/Task_Queue_Tool Queue]=== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"|The "Queue" tool helps you track and manage the tasks created by the module.<br/> | ||
| + | It allows you to view and interact with task details, including task IDs, statuses, and related items.<br/> | ||
| + | You can filter tasks, execute actions like deleting or running tasks, and even use mass actions for bulk operations.<br/> | ||
| + | For detailed guidance on using this tool, please refer to the dedicated article available [https://www.docs.modulesgarden.com/Queue here]. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_40_0.png]] | ||
|} | |} | ||
| Line 846: | Line 974: | ||
Clicking on a container from the stack view opens a dedicated detail panel with full technical insight. <br/> | Clicking on a container from the stack view opens a dedicated detail panel with full technical insight. <br/> | ||
The view is divided into multiple sections for clarity and easier access to specific information.<br/> | The view is divided into multiple sections for clarity and easier access to specific information.<br/> | ||
| − | Use the same action buttons: '''Start''', '''Stop''', | + | Use the same action buttons: '''Start''', '''Stop''', '''Restart''', and '''Recreate''' directly within the container view.<br/> |
* '''Service management options''' | * '''Service management options''' | ||
* '''Container details'''<br/> | * '''Container details'''<br/> | ||
| Line 856: | Line 984: | ||
|} | |} | ||
| − | === | + | ===Swarm View=== |
{| | {| | ||
|style="padding: 10px 0px 15px 15px;"|Users can effortlessly start, stop, or restart their containers using intuitive action buttons ''('''Start''', '''Stop''', and '''Restart''').'' | |style="padding: 10px 0px 15px 15px;"|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 | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_47_1.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''Container assigned to swarm stack view.'''<br/> | ||
| + | Clicking on a container opens a dedicated detail panel with full technical insight. <br/> | ||
| + | The view is divided into multiple sections for clarity and easier access to specific information.<br/> | ||
| + | Use the same action buttons: '''Start''', '''Stop''', and '''Restart''' directly within the container view.<br/> | ||
| + | * '''Service management options''' | ||
| + | * '''Container details'''<br/> | ||
| + | * '''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. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 25px;"|[[File:PDC_47_2.png]] | ||
| + | |} | ||
| + | |||
| + | ===Container View=== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"|Users can effortlessly start, stop, restart or recreate their containers using intuitive action buttons ''('''Start''', '''Stop''','''Restart''', and '''Recreate''').'' | ||
* Service management options | * Service management options | ||
* Container details | * Container details | ||
| Line 916: | Line 1,068: | ||
|} | |} | ||
| − | = | + | ==Use Cases== |
{| | {| | ||
| − | |style="padding: 10px 0px 30px 15px;"| | + | |style="padding: 10px 0px 30px 15px;"|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.<br/> |
| − | + | Each scenario focuses on a real-world need, such as defining custom networks, overriding commands, attaching volumes, or using configurable options.<br/> 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==== |
{| | {| | ||
| − | |style="padding: 10px 0px 30px 15px;"|'''The module does not | + | |style="padding: 10px 0px 15px 15px;"|Portainer Docker Containers For WHMCS allows defining custom proxy networks directly inside stack templates.<br/> |
| − | + | 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.<br/> | |
| − | + | ||
| + | Network definitions are added inside the <code>template_stack_file</code> field of an App Template. <br/> | ||
| + | Each stack can create its own dedicated bridge network using dynamic variables such as <code>proxy_{$hosting.id}</code>, ensuring container isolation and predictable DNS-based service discovery inside the stack. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''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 <code>docker-compose.yml</code>. | ||
| + | # Include a custom network declaration and attach your services to that network.<br/> '' (Example below is not a full Docker Compose file; it focuses on showing the structure.)'' | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''Sample configuration using Traefik & custom proxy network:''' | ||
| + | |||
| + | <pre> | ||
| + | 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 | ||
| + | </pre> | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"|'''Notes:''' | ||
| + | * Every stack may define its own internal bridge network such as <code>proxy_{$hosting.id}</code>. <br/>These networks are removed automatically when the stack is terminated. | ||
| + | * Traefik and application containers communicate through the internal proxy network. <br/>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==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 30px 15px;"|This use case applies when a provider needs full control over how an application container is executed.<br/> | ||
| + | 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., <code>bash my-script.sh {$service.id}</code>) | ||
| + | |||
| + | * '''container_ports''' - custom list of container ports | ||
| + | (e.g., <code>["80/tcp","443/tcp"]</code>) | ||
| + | |||
| + | * '''container_image''' - override the image and tag | ||
| + | (e.g., <code>nginx:latest</code>) | ||
| + | |||
| + | These options enable fine-tuned deployments when the default Portainer template settings are insufficient.<br/> | ||
| + | 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==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"| | ||
| + | This use case shows how providers can attach custom volumes ''(both '''bind''' and '''local''')'' to containers created through App Templates. <br/> | ||
| + | The module introduces the <code>container_volumes</code> configuration field, allowing you to map host paths to container directories and control read-only or read-write access. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''How to define volumes in an App Template''' | ||
| + | # Go to: '''App Templates → Applications''' | ||
| + | # Open the selected application | ||
| + | # Edit the <code>container_volumes</code> field; create it if it does not exist | ||
| + | # Provide a JSON list of volume objects using Smarty-safe tags <code>{ldelim}</code> and <code>{rdelim}</code> | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''JSON Structure'''<br/> | ||
| + | Each volume object contains: | ||
| + | * <code>bind</code> - path on the host (or <code>null</code> to allow Docker to assign a local volume) | ||
| + | * <code>container</code> - path inside the container | ||
| + | * <code>readonly</code> - <code>true</code> for read-only, <code>false</code> for read-write | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"| | ||
| + | '''Example configuration:''' | ||
| + | <pre>[ | ||
| + | {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} | ||
| + | ]</pre> | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"| | ||
| + | '''Example explained (Nginx):''' | ||
| + | * <code>/etc/nginx</code> is mounted as read-only | ||
| + | * <code>/usr/share/nginx/html</code> is mounted as read-write | ||
| + | * <code>/var/log/nginx</code> stores logs in a customer-specific directory on the host: | ||
| + | <code>/opt/nginx/logs{$service.id}</code> | ||
| + | |||
| + | Volumes displayed in Portainer may include automatically generated Docker volume IDs or bind paths, depending on configuration. | ||
| + | |} | ||
| + | |||
| + | ====Overriding Default Container Username==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"|This use case explains how to define a custom user for the built-in container terminal. <br/> | ||
| + | By default, Portainer executes terminal sessions as <b>root</b>. The module allows overriding this behavior by defining a <code>terminal_user</code> 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., <code>www-data</code> for WordPress), | ||
| + | * the image defines multiple system users, and one of them should be used for security or compatibility reasons. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"| | ||
| + | '''How to set a custom terminal user''' | ||
| + | # Go to: '''App Templates → Applications''' | ||
| + | # Open the application you want to modify | ||
| + | # Add or edit the <code>terminal_user</code> setting | ||
| + | # Enter a username that exists inside the Docker image <br/>(e.g., <code>www-data</code>, <code>node</code>, <code>postgres</code>, or a numeric <code>uid</code> / <code>uid:gid</code> pair) | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"|'''Accepted formats'''<br/> | ||
| + | The terminal user must match one of the following formats: | ||
| + | * <code>user</code> | ||
| + | * <code>user:group</code> | ||
| + | * <code>uid</code> | ||
| + | * <code>uid:gid</code> <br/> | ||
| + | Portainer will reject values that do not exist in <code>/etc/passwd</code> inside the container. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"| | ||
| + | '''Behavior on deployment & reinstall''' | ||
| + | * If <code>terminal_user</code> is defined → the module uses it for the terminal session | ||
| + | * If not defined → the user defaults to <b>root</b> | ||
| + | * During reinstall, the correct terminal user is restored automatically ''(stored in WHMCS custom fields for persistence)'' | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"|'''Example: WordPress container terminal'''<br/> | ||
| + | To run terminal commands as the web server user instead of root, define:<br/> | ||
| + | <pre> | ||
| + | terminal_user = www-data | ||
| + | </pre> | ||
| + | |||
| + | 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==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"|This use case describes how to use WHMCS '''Configurable Options''' (CO) as dynamic values inside stack templates. <br/> | ||
| + | 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.<br/> | ||
| + | |||
| + | Configurable Options become available inside App Template fields using the <code>{$params.configoptions.*}</code> variable. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"| | ||
| + | '''How to use Configurable Options inside a stack''' | ||
| + | # Create or edit a WHMCS Configurable Options Group ''(e.g., <b>Disk Size</b>, <b>CPU Limit</b>, <b>Memory Limit</b>)''.<br/> | ||
| + | # Assign these options to your product that uses Portainer Docker Containers.<br/> | ||
| + | # Go to: '''App Templates → Applications → Application details.''' | ||
| + | # Edit the field where you want to use the value ''(e.g., <code>labels</code>, <code>template_stack_file</code>, <code>environment</code>, etc.)''. | ||
| + | # Insert the CO variable using: | ||
| + | <pre>{$params.configoptions.option_name}</pre> | ||
| + | |||
| + | The module automatically injects the current value when creating or reinstalling the service. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"| | ||
| + | '''Example: Passing "Disk Size" from WHMCS to container labels'''<br/> | ||
| + | If you defined a Configurable Option: | ||
| + | * <b>disk_size</b> = 15 MB | ||
| + | |||
| + | Then inside the '''App Template → labels''' field you can use: | ||
| + | <pre> | ||
| + | traefik.enable=1 | ||
| + | traefik.docker.network=bridge | ||
| + | disk_customoption={$params.configoptions.disk_size} | ||
| + | </pre> | ||
| + | |||
| + | During service creation, this will appear in Portainer as: | ||
| + | <pre> | ||
| + | disk_customoption = 15 | ||
| + | </pre> | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"| | ||
| + | '''Example inside docker-compose (template_stack_file)'''<br/> | ||
| + | You can also use CO values inside stack compose files: | ||
| + | <pre> | ||
| + | version: "3.9" | ||
| + | |||
| + | services: | ||
| + | app: | ||
| + | image: ubuntu:latest | ||
| + | environment: | ||
| + | DISK_SIZE: "{$params.configoptions.disk_size}" | ||
| + | labels: | ||
| + | - "disk.size={$params.configoptions.disk_size}" | ||
| + | </pre> | ||
| + | |} | ||
| + | |||
| + | ====Improving Container Security Using Alternative Runtimes==== | ||
| + | {| | ||
| + | |style="padding: 10px 0px 15px 15px;"| | ||
| + | This use case shows how container isolation can be improved by using an alternative container runtime instead of the default one.<br/> | ||
| + | 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. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 20px 25px;"|[[File:PDC_UseCase_1.png]] | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"| | ||
| + | '''Example: Using Sysbox Runtime'''<br/> | ||
| + | One example of an alternative runtime is '''[https://github.com/nestybox/sysbox 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 <code>procfs</code> and <code>sysfs</code>, | ||
| + | * locking initial container mounts. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 15px 15px;"| | ||
| + | '''Running System-Level Software'''<br/> | ||
| + | Sysbox also allows containers to run system-level software that normally requires elevated privileges, such as: | ||
| + | * <code>systemd</code> | ||
| + | * Docker and Docker-in-Docker | ||
| + | * Kubernetes / K3s | ||
| + | * buildx (including multi-architecture builds) | ||
| + | |||
| + | These workloads can run without privileged containers or special images. | ||
| + | |} | ||
| + | {| | ||
| + | |style="padding: 0px 0px 30px 15px;"| | ||
| + | '''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= | ||
| + | {| | ||
| + | |style="padding: 10px 0px 30px 15px;"|'''1. If any technical or unclear environment variables are visible to clients, you can easily make them more user-friendly using the Translations tool.''' <br/> | ||
| + | Take a moment to review the [https://www.docs.modulesgarden.com/Translations_Tool Translations Tool] documentation and its [https://www.docs.modulesgarden.com/Translations_Tool#Missing_Elements Missing Elements] section to ensure all custom lines are properly translated. | ||
|} | |} | ||
Latest revision as of 13:52, 12 December 2025
[edit] 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. 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. |
- 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 |
[edit] 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/'. |
|
[edit] 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'. |
|
[edit] 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:
|
|
|
| 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'. |
|
[edit] 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'. |
|
[edit] 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. |
[edit] Applications
This section allows you to load available templates from your connected Portainer environment and manage them within WHMCS.
|
|
| Once templates are imported, you can use action buttons to edit, duplicate, or delete them. Mass actions are also available for bulk management. |
|
[edit] 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:
|
|
| 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. |
[edit] 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:
|
|
Alternatively, to configure Docker-in-Docker (DinD), you also need to set up its configuration
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.
|
|
20. Set up 'Container Limits':
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:
|
|
| 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:
|
|
| 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:
|
|
|
| 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. |
|
[edit] Docker-in-Docker Workflow
When the Docker-in-Docker feature is enabled, the module automatically:
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 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"]
|
| 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. |
| Recommended Reading: |
Compatibility Notes:
|
[edit] 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. |
[edit] 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. |
[edit] 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. |
[edit] 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:
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 |
[edit] 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):
If the default command is not compatible with the container image, you can override it by editing the |
|
[edit] 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:
|
|
{literal}MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}{/literal}
Important: Skipping the |
|
[edit] 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., |
|
[edit] 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:
|
|
[edit] 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. |
|
| You can delete images one by one by clicking on them. To delete all images at once, use the additional action button. |
|
[edit] 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. |
|
[edit] Logs
| The 'Logs' tab is where the module logs are stored. You can filter the module logs by type with the 'Show' buttons:
All information on Logs can be found in the dedicated Logs article. |
|
[edit] 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. |
|
[edit] Dashboard
| The 'Dashboard' provides information and statistics related to the functions of the module.
Press "i" to see service details. |
|
[edit] Admin Area
Stack-based product type view:
|
|
Container-based product type view:
|
|
[edit] 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. |
|
[edit] 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' .
The above-mentioned information has to be consistent with the data in your Portainer panel. Now, complete this field as presented below. |
|
| 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. |
[edit] 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. Service Actions that can be performed on either stack or container based product type: start, stop, and restart |
[edit] 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. |
|
| Container assigned to stack view. Clicking on a container from the stack view opens a dedicated detail panel with full technical insight.
|
|
[edit] Swarm View
Users can effortlessly start, stop, or restart their containers using intuitive action buttons (Start, Stop, and Restart).
|
|
| Container assigned to swarm stack view. Clicking on a container opens a dedicated detail panel with full technical insight.
|
|
[edit] Container View
Users can effortlessly start, stop, restart or recreate their containers using intuitive action buttons (Start, Stop,Restart, and Recreate).
|
|
[edit] 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. |
|
[edit] 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. |
|
[edit] Container Logs
| Clients have access to detailed container logs. |
|
[edit] 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. |
|
[edit] 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. |
|
[edit] 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. |
[edit] 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 |
How to define a custom proxy network in a Stack Application:
|
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:
|
[edit] 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:
(e.g.,
(e.g.,
(e.g.,
These options enable fine-tuned deployments when the default Portainer template settings are insufficient. |
[edit] 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. |
How to define volumes in an App Template
|
| JSON Structure Each volume object contains:
|
|
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):
Volumes displayed in Portainer may include automatically generated Docker volume IDs or bind paths, depending on configuration. |
[edit] 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 This is useful when:
|
|
How to set a custom terminal user
|
| Accepted formats The terminal user must match one of the following formats:
Portainer will reject values that do not exist in |
|
Behavior on deployment & reinstall
|
| 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. |
[edit] 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 |
|
How to use Configurable Options inside a stack
{$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
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)
version: "3.9"
services:
app:
image: ubuntu:latest
environment:
DISK_SIZE: "{$params.configoptions.disk_size}"
labels:
- "disk.size={$params.configoptions.disk_size}"
|
[edit] 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. 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 Sysbox improves container isolation by:
|
|
Running System-Level Software
These workloads can run without privileged containers or special images. |
|
Important Notes
|
[edit] 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. |
[edit] 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. |
[edit] 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. 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. |
[edit] Common Problems
| 1. When you have problems with connection, check whether your SELinux or firewall does not block ports. |





























































