Using Docker | Plesk Obsidian documentation

Docker is a powerful platform designed for running applications within isolated containers. This technology allows you to utilize specific software, such as Redis or MongoDB, or particular versions of software that might not be natively supported by your operating system or could require complex compilation processes. By encapsulating applications and their dependencies, Docker ensures consistency across different environments.

Within Plesk, Docker is seamlessly integrated as an extension, providing a robust interface to manage your containerized applications. This integration empowers you to efficiently run and manage containers derived from various Docker images, supporting operations on both your local host and remote servers.

This comprehensive guide will walk you through the essential steps to create, configure, and effectively manage Docker containers directly within the Plesk environment. Furthermore, you will gain insights into controlling and utilizing remote Docker hosts via your Plesk installation, expanding the capabilities of your deployment.

Requirements and Limitations

Warning: The Docker extension directly downloads images from Docker Hub without any pre-configuration. It is crucial to understand that some Docker containers or their embedded software are designed for trusted environments and may necessitate additional security configurations. Before deploying any downloaded images within Plesk, it is your responsibility to implement the necessary security enhancements. For detailed instructions, always refer to the specific documentation provided by the container or software vendor. For instance, you can consult the security section in the Redis documentation for guidance.

• Docker support in Plesk is available for the following operating systems: CentOS 7, Red Hat Enterprise Linux 7, Debian 10, Debian 11, Debian 12, Ubuntu 18.04, Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, AlmaLinux 8.x, AlmaLinux 9.x, Rocky Linux 8.x, and Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later.
• For Plesk installations on Windows, it is possible to utilize Docker when it is installed on a remote machine.
• It is not possible to use Docker within a Plesk instance that is itself deployed inside a Docker container.
• Accessing remote Docker services through Plesk requires an additional license. This license can be acquired either separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker is exclusively designed to operate on x64 systems.
• Direct migration or backup of Docker containers within Plesk is not supported. However, it is possible to back up the data utilized by containers (refer to the Volume Mapping section below) or to download snapshots of your containers.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or a more recent version is fully supported. Please note that with this update, newly created CentOS 7-based containers have their firewalls enabled by default, a measure introduced by Virtuozzo to enhance security. Plesk administrators are therefore required to manually configure the firewall to ensure that all necessary ports for Plesk's operation are open.

Prerequisites

Before you can begin leveraging the capabilities of Docker within your Plesk environment, it is essential that the Docker extension is properly installed on your Plesk server.

• If you hold administrator privileges for your Plesk instance, you can easily install the extension directly from the Extensions Catalog.
• Alternatively, if you are not the Plesk administrator, please reach out to your hosting provider and request that they install the Docker extension on your behalf.

Once the extension has been successfully installed, you will be prepared to start utilizing Docker. You will notice the new Docker option conveniently located within the Navigation Pane of your Plesk interface.

Containers

You can access a vast collection of images from Docker Hub directly within the Run Container catalog, accessible via Docker > Containers > Run Container.

To access the catalog and begin your container deployment:

• If you have not previously installed any containers, navigate to Docker > Containers, and then click the Run Container button.
• If you have previously installed containers, simply go to Docker > Containers, and click the plus icon to add a new one.

To efficiently locate available images, utilize the integrated search box.

You can refine your search by specifying the image name, the repository, or a combination of both.

The following repositories are available for your search:

• Local repository: This repository contains images that have already been downloaded and are now stored on your Plesk server with Docker. For more comprehensive details, refer to the Managing Local Images section later in this guide.
• Docker Hub: The official Docker image registry, offering a wide array of public and private images.

Many applications offer multiple versions, allowing you to select a specific iteration by choosing the appropriate tag, as illustrated below:

To run a new container, follow these steps:

1. Navigate to Docker > Containers > Run Container.
2. Utilize the search box to find your desired images within the catalog. If an image is stored locally, (local) will be appended after its version number.
3. To view detailed descriptions and documentation for an image on Docker Hub, click the more info icon . Note that this option is not available for local images.
4. Click on the image card to proceed.

   • To run a specific version of the image, select your preferred version from the Image version drop-down menu and then click Next.
   • To run the latest available version of the chosen application, simply click Next.

5. Plesk will then initiate the creation of the container and prompt you to define its essential settings, such as environment variables. You can cancel this process at any point by clicking Cancel on the Settings screen. For a detailed breakdown of these settings, refer to the Container Settings section on this page.
6. After adjusting the settings to your requirements, click Run. The newly created container will then appear in the comprehensive list of containers located under the Containers tab.

Always review the Console Log to ascertain if the container is operating without any issues or errors.

Container Settings

Note: When you need to modify container settings, it is not necessary to stop the container beforehand. Plesk intelligently recreates the container with your newly saved settings, ensuring a seamless update process.

To access and edit the settings of an existing container, navigate to the Containers tab. Locate the desired container and click the settings icon positioned next to it.

Limiting Memory

By default, Docker containers operate with unlimited RAM usage. To impose a memory limit, select the Memory limit checkbox and then enter the desired maximum value in megabytes (MB) into the corresponding field.

Note: Currently, CPU and Disk usage cannot be limited for Docker containers within Plesk.

Note: Docker containers are considered administrator-level objects. Consequently, their resource usage (CPU, RAM, Disk) is not governed by subscription-level cgroup limits.

Automatic Start

If the option Automatic start after system reboot is not enabled, any websites utilizing this container might become unavailable following a system reboot. In such cases, you would be required to manually start the container to restore service.

Port Mapping

By default, Automatic port mapping is active. This configuration assigns a random, available port on the host system (e.g., 32768) to map to the container's internal exposed port.

To customize the port on the host system, deselect Automatic port mapping and then specify an alternative external port under Manual mapping. If the Manual mapping option does not appear after deselection, it indicates that the container itself does not expose any ports.

When employing manual mapping, Docker typically binds only to the specified port on the host system's localhost interface (127.0.0.1). This default behavior helps secure the application inside the container by making the port inaccessible from the internet. To allow Docker to bind to the specified port across all network interfaces of the host system, deselect the Make the port inaccessible from the Internet option. Be aware that doing so will make the application within the container publicly accessible from the internet via the specified port and any of the host system’s IP addresses.

Warning: Docker generally assumes that authentication mechanisms are handled by the application itself. However, this is not always the case (for example, MySQL/MariaDB typically disallows anonymous access by default, while Redis may permit it). Exposing an application inside a container to the internet without proper authentication and security measures can significantly increase its vulnerability to malicious attacks.

Volume Mapping

Docker volumes are persistent storage mechanisms that define directories on your server which are mounted directly into a Docker container. This ensures that data remains accessible from your host system and, crucially, is not deleted when you stop or remove a container.

Warning: Please be aware that any data stored within Docker volumes will not be included in standard Plesk backups. To prevent potential data loss for critical information, it is strongly recommended to back up any essential data residing in a volume using a third-party backup tool.

For more detailed information regarding data management within containers, please consult the official Docker documentation on volumes.

To establish a volume mapping, you need to specify the following:

• In the Host field: Provide the absolute path to the directory on your server that you intend to mount into the container.
• In the Container field: Specify the absolute path to the desired directory inside the container where the host directory will be mounted.

To map additional directories, simply click the Add one more button.

Setting Environment Variables

Environment variables play a critical role in configuring the application running inside a container. You may find it necessary to add new variables or modify existing ones to suit your application's requirements. Plesk offers the flexibility to add as many environment variables as needed.

Operations with Containers

Plesk provides a comprehensive set of actions you can perform on your Docker containers to manage their lifecycle effectively:

• You can readily Stop, Start, or Restart a container as needed. When performing these actions, the container will be recreated with its current settings.

  Note: It is critical to understand that if you have not saved your data to mounted volumes (as explained in the Volume Mapping section above), any unsaved data within the container will be lost upon recreation.

• To monitor container performance and troubleshoot issues, click the arrow icon adjacent to the container name to view its logs and real-time resource consumption.
• To adjust a container's configuration, such as environment variables or volume mappings, click the settings icon next to the container. This will open the Settings panel.
• You can easily rename a container by accessing its settings via Settings > Container name and updating the label.

For more advanced operations, click the more options icon located next to the container. This menu allows you to perform one or more of the following actions:

• Recreate: Rebuild a container using the same image version or a different one.
• Save as Image: Create a new Docker image based on the current state and custom settings of your container.
• Download Snapshot: Generate and download a snapshot of your container at a specific point in time.
• Remove: Delete the container from your Plesk environment.

Recreating a Container

The recreation of a container is typically performed when you intend to update the application running inside it to a newer version. However, this functionality allows you to rebuild a container using any application version available in the catalog, not just the latest one.

Crucially, all custom settings are preserved during the recreation process. To ensure the persistence of data used by the application within a container, it is essential to configure volume mapping before initiating the recreation. Volume mapping provides persistent access to the directories utilized inside a container. (For detailed information, please refer to the Volume Mapping section within container settings).

To recreate a container, follow these steps:

1. Navigate to Docker and click the more options icon adjacent to the container you wish to recreate.
2. From the container settings, click Recreate. You will then be prompted to specify the desired image version and whether to use the default environment variables for the new instance.

Using Remote Docker

While Plesk defaults to using Docker installed as a local service, it offers the flexibility to integrate with one or more Docker services deployed externally. It's important to remember that only one Docker service can be active at any given time. The currently active server can be identified within the Environments tab of the Docker settings page in Plesk.

Note: To manage remote Docker services, a specific Plesk license key add-on is required. Without this essential add-on, your management capabilities will be limited solely to the local Docker service running directly on the Plesk server.

Configuring Remote Services

Before integrating a remote Docker service with Plesk, you must properly configure the remote server where Docker is running. Follow the instructions detailed in the official Docker documentation to prepare it for use as a remote server within your Plesk environment.

Managing Remote Services

The process of establishing a secure connection between your Plesk server (equipped with the Docker extension) and a remote node hosting a Docker service is straightforward. The following detailed steps are applicable to both Plesk for Linux and Plesk for Windows installations.

These initial steps must be diligently performed on the remote host:

1. Create the /etc/docker/daemon.json configuration file for Docker, ensuring it contains the following content to enable TLS:

   {
     "hosts": ["tcp://0.0.0.0:2376", "unix:///var/run/docker.sock"],
     "tls": true,
     "tlsverify": true,
     "tlscacert": "/root/ca.pem",
     "tlscert": "/root/server-cert.pem",
     "tlskey": "/root/server-key.pem"
   }

2. Prepare the necessary .pem files for secure communication. You can adapt the following example. Remember to replace the placeholder IP address on line 4 with the actual IP address of your remote node before executing each command sequentially:

   openssl genrsa -aes256 -out ca-key.pem 4096
   openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
   openssl genrsa -out server-key.pem 4096
   openssl req -subj "/CN=192.0.2.1" -new -key server-key.pem -out server.csr
   openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem
   openssl genrsa -out key.pem 4096
   openssl req -subj '/CN=client' -new -key key.pem -out client.csr
   openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out cert.pem
   chmod 0400 ca-key.pem server-key.pem key.pem
   chmod 0444 ca.pem server-cert.pem cert.pem

3. Execute the following commands to modify the current Docker service, ensuring it automatically starts and operates correctly after host configuration changes:

   cp /lib/systemd/system/docker.service /etc/systemd/system/
   sed -i 's/\\ -H\\ fd:\\/\\///g' /etc/systemd/system/docker.service
   systemctl daemon-reload
   systemctl restart docker

4. Finally, save the outputs of the following files onto your local machine. These files contain critical client certificates and keys required for establishing a remote connection:

   cat key.pem
   cat cert.pem
   cat ca.pem

Once the remote host is configured, proceed to your local Plesk server to integrate the Docker remote host:

1. Navigate to Docker > Environments.
2. Click the Add Server button and accurately input the connection settings for your remote Docker server.
3. To immediately begin using this specific Docker service within Plesk, ensure the Set active option remains selected during configuration.

Upon successful configuration, the link to the active Docker service will become visible in the Navigation Pane.

To switch between multiple configured Docker services:

1. Access Docker > Environments.
2. From the displayed list of servers, select the desired Docker node you intend to use and click Set Active.

Alternatively, you have the option to set a Docker node as active directly while you are editing its settings.

Creating Images with Custom Settings

Should you wish to generate a new Docker image that incorporates modifications made to an existing container, the Save as Image command is the ideal tool. This function effectively captures a snapshot of your container's current state, subsequently registering it as a new image within your image catalog. This capability is particularly useful for creating specialized images with predefined custom settings, including specific environment variables.

To create a new image from one of your running containers, follow these steps:

1. Navigate to Docker > Containers.
2. Locate the container from which you want to create an image and click the more options icon next to it.
3. From the options, select Save as Image.
4. In the "Save <container name> as Image" side panel that appears, you will need to specify the following:
   • Image name: A descriptive name for your new custom image.
   • Tag: An optional tag, which typically denotes the image version. By default, if no tag is specified, it will be set as "latest".

The newly created image will then be visible in the Images tab, clearly marked as a Local image to distinguish it from images pulled from remote repositories.

Managing Local Images

Local images refer to Docker images that are persistently stored on your local disk. This local storage eliminates the need to re-download them from the Image Catalog whenever they are required, significantly speeding up deployment times and reducing bandwidth usage.

An image transitions to a local status under the following circumstances:

• When you select any version (or tag) of an image and its download process commences. Regardless of whether you later run a container from it or cancel the process (on the Settings screen), the image will be saved locally.
• Upon uploading an image directly to Docker within Plesk, using the Upload image function in the Docker Images tab.
• You have successfully created a custom image based on an existing container (refer to the Creating Images with Custom Settings section for details).
• If you have built an image using the Docker command-line interface directly on the server.

To download an alternative version of an image from the online catalog, click the Pull icon . From the subsequent drop-down menu, choose the specific version you wish to pull and then confirm by clicking Pull.

If Docker detects at least one downloaded version from a family of versions associated with a particular image, that image will be prominently marked as a Local image in the catalog. Plesk also provides a clear indication of how many local images are present for each product.

To efficiently manage your local images, including viewing and removing outdated versions:

1. Navigate to Docker > Images.
2. To quickly locate a specific local image, utilize the provided Search bar.
3. To examine all local images pertaining to a particular product, click the link displayed directly under the product name. This action will reveal all local image tags and the corresponding disk space they currently occupy.

Setting up Nginx to Proxy Requests from Domains to a Container

Many Docker containers are configured to expose specific ports, allowing applications running within them to be accessed. However, directly specifying non-standard ports in a website's URL can be cumbersome and user-unfriendly.

To overcome this, you can configure Nginx to proxy requests from your domains to the container's designated port. This setup enables your domains to operate on standard web ports (such as 80 or 443), eliminating the need for users to explicitly include the port number in the URL.

Requirements

• Nginx must be actively running within your Plesk environment.
• You must manually map the internal port of your Docker container to a specific port on the host system (e.g., 32768).

To manually map the port inside a container, follow these steps:

1. Navigate to Docker > Containers.
2. Click the settings icon next to the container you intend to configure.
3. Disable the Automatic port mapping option.
4. Manually map the internal port of the container to a specific port on your system (for example, 32768). You also have the option to make this mapped host port inaccessible from the internet for enhanced security.

Once the port is manually mapped, you can proceed to configure Nginx to proxy requests from your domains to this specific host port. This allows your domains to leverage a standard Nginx port (e.g., 80 or 443). To enable this functionality, you will need to add a proxy rule within your domain's settings.

To add a rule for Nginx within the domain settings, navigate to Websites & Domains > [your domain] > Docker Proxy Rules > Add Rule. Here, you will specify the following parameters:

• URL: Define the URL of the website or a specific section of the website that utilizes an application running within a Docker container.
• Container: Select the relevant application that is operating as a Docker container.
• Port: Choose one of the port mappings previously configured in the container's settings. Nginx will then proxy incoming requests to this specified port on the host system.

These proxy rules are intricately implemented within the web server's configuration, typically found in the website’s nginx.conf file (located at /var/www/vhosts/system/$domain/conf/). An example configuration snippet is shown below:

#extension docker begin
location ~ ^/.\* {
    proxy\_pass http://0.0.0.0:9080;
    proxy\_set\_header Host             $host;
    proxy\_set\_header X-Real-IP        $remote\_addr;
    proxy\_set\_header X-Forwarded-For  $proxy\_add\_x\_forwarded\_for;
}
#extension docker end

It is important to note that these proxy rules are designed to function effectively even on servers situated behind Network Address Translation (NAT).

Note: Docker containers that are connected to a website via Proxy Rules are generally not included in the calculation of the subscription's disk space usage. An exception occurs when a website directory is mounted into a Docker container as a volume; in such cases, all files located within that container will contribute to the website's reported disk space usage.

Deploying Docker Compose YAML Files

Plesk offers convenient methods for deploying Docker Compose YAML files, enabling you to manage multi-container Docker applications effortlessly. You can deploy these files using an integrated online text editor, by uploading a file directly from your local storage, or by selecting a Docker Compose file already present within a website’s Home directory. Plesk supports typical operations on these application stacks, including up (which encompasses pull and force-recreate actions), stop, and down. Furthermore, you retain the ability to modify and update your deployed stacks at any point after their initial creation.

Note: It is important to understand that this section is specifically for deploying Docker Compose YAML files. You cannot use this interface to deploy Dockerfiles or other supplementary files required by an application.

To deploy a Docker Compose file, follow these steps:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a suitable project name for your stack and then choose one of the following methods for deploying your Docker Compose file:
   • Editor: Utilize the integrated editor to define or paste the content of your Docker Compose file directly.
   • Upload: Select and upload a Docker Compose file from your local storage.
   • Webspace: Choose a Docker Compose file that is already stored within a domain’s Home directory. If selecting this option, you will need to specify the domain where the file is located and then browse to the exact Compose file path.

This functionality also allows you to declare and build custom containers as part of your stack. Any artifacts generated during the build process will be conveniently placed inside the respective website’s Home directory.

For a comprehensive understanding of the Compose file format and its capabilities, please refer to the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a highly effective container management software designed to simplify the deployment of containers and application stacks. It provides a user-friendly interface for monitoring container status and logs, facilitating user and team creation, enhancing environmental security, and much more, thereby streamlining your container orchestration efforts.

To install Portainer within your Plesk Docker environment, simply navigate to Docker > Install Portainer. Once the installation process is complete, you can begin managing your Portainer containers by going to Docker > Go to Portainer.

Note: Please be aware that Portainer is currently offered as a beta feature within Plesk.

For extensive details and guidance on utilizing Portainer, we recommend consulting the official Portainer documentation.