Using Docker | Plesk Obsidian documentation

Docker is a powerful platform that revolutionizes how applications are developed, shipped, and run by encapsulating them in lightweight, portable units called containers. This technology allows users to deploy specific software, such as Redis or MongoDB, or to utilize particular software versions that might not be natively supported by their operating system or that require complex compilation processes.

Integrated seamlessly as a Plesk extension, Docker empowers you to efficiently run and manage containers built from a wide array of Docker images. This integration extends capabilities to both local hosts and remote servers, offering flexible deployment options. This guide will walk you through the essential steps for creating, configuring, and managing Docker containers within Plesk, alongside detailing how to control remote Docker hosts directly from the Plesk interface.

Requirements and Limitations for Docker in Plesk

Warning: The Docker extension directly downloads images from Docker Hub without any pre-configuration. It is crucial to understand that some Docker containers or the software within them are intended for trusted environments only and may necessitate additional security setup. Before deploying these downloaded images in Plesk, you are responsible for enhancing their security. Always refer to the official documentation provided by the container or software vendor for specific security instructions. For example, refer to the security section in the Redis documentation for detailed guidance.

• Docker is fully supported in Plesk for a range of operating systems, including: 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 on Windows installations, Docker can be utilized when installed on a remote machine. For more details, consult the section on Utilizing Remote Docker Services later in this guide.
• It is not possible to run Docker within a Plesk instance that is itself deployed as a Docker container.
• Accessing remote Docker services through Plesk requires an additional license. This can be acquired either separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker functionality is exclusively available on x64 systems.
• Docker containers managed within Plesk cannot be directly migrated or backed up. However, it is possible to back up the data utilized by these containers (see Volume Mapping below) or download snapshots for preservation.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or a later version is supported. It's important to note that with this update, newly created CentOS 7-based containers have the firewall enabled by default due to Virtuozzo’s enhanced security measures. Plesk administrators must manually configure the firewall to ensure that all necessary ports for Plesk operations are open.

Prerequisites for Using Docker in Plesk

Before you can begin leveraging Docker's capabilities, the Docker extension must be properly installed on your Plesk server. If you are the Plesk administrator, you can install the extension directly from the Extensions Catalog. Otherwise, you should contact your hosting provider and request that they install the extension for you.

Once the extension is successfully installed, you will find the Docker option conveniently located in the Navigation Pane, indicating that you are ready to explore and utilize Docker within your Plesk environment.

Managing Docker Containers in Plesk

Accessing and Running Containers

You can effortlessly access a vast array of images from Docker Hub directly within the Run Container catalog of Plesk. To navigate to this catalog:

• If you have not previously installed any containers, go to Docker > Containers, and click Run Container.
• If you have already installed containers, navigate to Docker > Containers, and click the plus icon .

To locate available images, simply utilize the search box. You can specify the image name, the repository, or a combination of both to refine your search.

The following repositories are available for your search queries:

• Local repository: This repository houses local images that have already been downloaded and are currently stored on your server with Docker. For more comprehensive details, please refer to the section on Managing Local Docker Images.
• Docker Hub: The official Docker image registry.

It's important to note that many applications offer multiple versions. You can easily run a specific version of an application by selecting the appropriate tag from the available options, as illustrated below:

To successfully run a new container, follow these steps:

1. Navigate to Docker > Containers > Run Container.
2. Utilize the search box to locate the desired images within the catalog. If an image is stored locally, it will be indicated by (local) next to its version.
3. To view the image description and access its official documentation on Docker Hub, click the more info icon . This option is not available for local images.
4. Click on the image card to proceed.
   • To run a specific version, select the desired image version from the Image version drop-down menu and click Next.
   • To run the latest available version of the chosen application, simply click Next.

   Plesk will then initiate the creation of a new container and prompt you to define its essential settings, such as environment variables, before launching it. You have the option to cancel the container launch at any point by clicking Cancel on the Settings screen. For a detailed overview of these settings, refer to the Configuring Container Settings section on this page.

5. After meticulously adjusting the settings to your requirements, click Run. The newly launched container will then appear in the comprehensive list of containers located in the Containers tab, indicating its active status.

It is always recommended to check the Console Log to ascertain if the container is operating smoothly and without any issues.

Configuring Container Settings

Note: When you need to modify container settings, it is not necessary to stop the container first. 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. Then, click the settings icon situated next to the specific container you wish to modify.

Limiting Memory Usage

By default, Docker containers are provisioned with unlimited RAM usage. To impose a specific memory limit, select the Memory limit checkbox and input the desired limit value in megabytes (MB) into the corresponding field.

Note: Currently, there are no provisions to limit CPU or Disk usage for Docker containers directly within Plesk.

Note: Docker containers are considered administrator-level objects and, as such, are not governed by subscription-level cgroup limits (which typically control CPU, RAM, and Disk usage).

Automatic Start After Reboot

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

Port Mapping Configuration

By default, Automatic port mapping is activated, which means the container's internal port is automatically mapped to an arbitrary, available port on the host system (e.g., 32768).

To manually specify the port on the host system, deselect Automatic port mapping and enter a different external port in the Manual mapping field. If the Manual mapping option does not appear after deselection, it indicates that the container is not configured to 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) by default. This configuration enhances security by making the port inaccessible from the Internet, thereby safeguarding the application within the container from external attacks. To allow Docker to bind to the specified port across all network interfaces of the host system, deselect Make the port inaccessible from the Internet. Be aware that enabling this will make the application inside the container accessible from the Internet via the specified port and any of the host system’s IP addresses.

Warning: Docker generally assumes that authentication is handled by the application itself. However, this is not always the case (for instance, MySQL/MariaDB typically disallows anonymous access by default, whereas Redis might permit it). Making an application within a container accessible from the Internet without proper authentication can expose it to potential attacks by malicious actors.

Volume Mapping

Docker volumes serve as designated directories on your server that are mounted to a Docker container. This mechanism provides persistent storage, allowing data to persist even when containers are stopped or deleted, and making it accessible directly from your host system.

Warning: Data stored within Docker volumes will not be automatically included in Plesk backups. To prevent any data loss, it is imperative to back up all essential data residing in a volume using a reliable 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 within the container.
• In the Container field: Provide the absolute path to a specific directory inside the container where the host directory will be mounted.

To map additional directories, simply click Add one more.

Setting Environment Variables

Environment variables are crucial for configuring the application running inside a container. You may frequently need 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 necessary.

Performing Operations on Containers

Plesk provides a comprehensive set of operations that you can perform on your Docker containers:

• Control Container State: You can effortlessly stop (Stop), start (Start), or restart (Restart) a container. In each of these actions, the container will be recreated based on its current configuration settings.

  Note: If you have not saved the data to mounted volumes (refer to the Volume Mapping section above), any unsaved data will be lost during these operations.

• View Logs and Resources: Click the arrow next to the container to access its operational logs and monitor its resource consumption, providing valuable insights into its performance.
• Modify Settings: Click the settings icon next to the container to adjust various settings, including environment variables and volume mapping (accessible via Settings).
• Rename Container: You can easily rename a container by navigating to its settings (Settings > Container name) and inputting a new name.

For additional advanced operations, click the more options icon next to the container. This will reveal a dropdown menu offering the following functionalities:

• Recreate: Rebuild a container using the current image version or select an alternative version.
• Save as Image: Create a new image based on the container, incorporating your custom settings.
• Download Snapshot: Generate and download a snapshot of the container's current state.
• Remove: Delete the container permanently.

Recreating a Container

Container recreation is a common operation, often necessary when you need to update the application running within it to a newer version. This process allows you to rebuild a container using any application version available in the catalog, not exclusively newer ones.

Crucially, all custom settings you have applied to the container are meticulously preserved during the recreation process. To ensure the preservation of data utilized by the application inside the container, it is vital to establish volume mapping before initiating a container recreation. Volume mapping provides persistent access to directories used within a container (for detailed instructions, refer to Volume Mapping in the container settings section).

To recreate a container, follow these steps:

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

Utilizing Remote Docker Services in Plesk

By default, Plesk is configured to use Docker installed as a local service on the same machine. However, for enhanced flexibility and scalability, you have the option to integrate one or more Docker services that are installed on external, remote machines. It's important to note that only one Docker service, whether local or remote, can be active and managed within Plesk at any given time. The currently active server is clearly displayed in the Environments tab of the Docker settings page in Plesk.

Note: Managing remote Docker services requires a specific Plesk license key add-on. Without this add-on, your management capabilities will be limited to the local Docker service running directly on the Plesk server.

Configuring Remote Docker Services

To prepare a remote server to function as a Docker host within Plesk, you must configure it precisely as outlined in the official Docker documentation regarding HTTPS setup. This ensures secure communication between Plesk and your remote Docker instance.

Managing Remote Docker Services

Plesk facilitates the establishment of secure connections between a Plesk server (with the Docker extension installed) and a remote node hosting the Docker service.

The following detailed steps are applicable for configuring both Plesk for Linux and Plesk for Windows environments.

These steps must be diligently performed on the remote host where Docker is installed:

1. Create the configuration file for Docker, named `/etc/docker/daemon.json`, and populate it with the following content:

   {
       "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` certificate files. You can use the following example script. Ensure you replace the 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 starts automatically 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. For subsequent use by the client to connect remotely, save the outputs of the following files onto your local machine:

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

Now, on your local Plesk server, proceed with configuring the Docker remote host:

1. Navigate to Docker > Environments.
2. Click Add Server and accurately specify all the settings pertinent to the remote server hosting Docker.
3. To immediately begin using this specific Docker service within Plesk, ensure that the Set active option remains selected.

Once successfully configured, a direct link to Docker will conveniently appear in the Navigation Pane.

To effortlessly switch between different Docker services (local or remote), follow these steps:

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

Alternatively, you can also designate a Docker node as active directly while in the process of editing its settings.

Creating Custom Docker Images from Containers

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

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

Navigate to Docker > Containers. Locate the container from which you want to create an image, click the more options icon next to it, and then select Save as Image. In the subsequent Save <container name> as Image side panel, you will need to specify the following:

• Image name: Provide a unique and descriptive name for your new custom image.
• Optional Tag: Here, you can specify a version for your image. If no tag is provided, the default version will be "latest".

The newly created image will then prominently appear in the Images tab and will be clearly identified as a Local image.

Managing Local Docker Images

Local images are Docker images that are stored directly on your server's local disk. This means they do not need to be downloaded again from the online Image Catalog, significantly speeding up container deployment.

An image becomes a local image under several circumstances:

• When you select and begin downloading any version (tag) of an image. Even if you later run a container from it or cancel the running process on the Settings screen, the image is retained locally.
• When you upload an image to Docker within Plesk using the Upload image option in the Docker Images tab.
• When you create a custom image directly from an existing container (as detailed in the Creating Custom Docker Images from Containers section).
• When you build an image manually using the command line interface.

To download an alternative version of an image from the online catalog, click the Pull icon , select the desired version from the drop-down menu, and then click Pull.

If Docker has at least one downloaded version belonging to a specific image, that image will be marked as a Local image in the catalog. Plesk will also indicate the total number of local images available for that particular product.

To effectively manage your local images and remove outdated ones, follow these steps:

1. Navigate to Docker > Images.
2. To quickly locate a specific local image, use the provided Search bar.
3. To view all local images associated with a particular product, click the link displayed under the product's name. This action will present all local images, their respective tags, and the disk space they occupy.

Configuring Nginx for Docker Proxy Requests

Many Docker containers are designed to expose specific ports, making the applications running within them accessible. When integrating a Dockerized application into your website, manually specifying a non-standard port in its URL can be inconvenient for users. To address this, you can configure Nginx to proxy requests from your domains to these container ports. This allows your domains to utilize standard web ports (such as 80 or 443) without the need for users to explicitly include the port number in the URL.

Requirements for Nginx Proxying:

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

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

1. Go to Docker > Containers and click the settings icon next to the container you wish to configure.
2. Deactivate the Automatic port mapping option.
3. Manually map the internal port of the container to a specific port on your host system (e.g., 32768). You have the option to make this mapped port inaccessible from the Internet for added security.

Once the port mapping is established, you can configure Nginx to proxy requests from your domains to this host port, enabling domains to use a standard Nginx port (such as 80). To achieve this, you need to add a specific rule within your domain settings:

To add a proxy rule for Nginx in your domain settings, navigate to Websites & Domains > select your domain > Docker Proxy Rules > Add Rule. Here, you will specify the following details:

• URL: Define the URL of your website that utilizes the application running within the Docker container. This can be for the main website or a specific section/path of it.
• Container: Select the Docker container application that you want to proxy requests to.
• Port: Choose one of the port mappings that were previously defined in the container settings (specifically, an internal container port mapped to a port on your host system). Nginx will then proxy incoming requests to this designated port on the system.

These proxy rules are implemented directly within the web server configuration, typically found in the website’s `nginx.conf` file (located in `/var/www/vhosts/system/$domain/conf/`):

#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;
}

It's worth noting that proxy rules generally function effectively on servers deployed behind a Network Address Translation (NAT) gateway.

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

Deploying Docker Compose YAML Files

Plesk offers robust support for deploying applications defined by Docker Compose YAML files. You can deploy these files through various convenient methods: using an online text editor to define content, uploading a file from your local storage, or by selecting a Docker Compose file that is already stored within a website's Home directory. Furthermore, Plesk supports typical stack operations such as `up` (which includes `pull` and `force-recreate` functionalities), `stop`, and `down`. After a stack has been created, you retain full capability to modify and update it as needed.

Note: This section specifically addresses the deployment of Docker Compose YAML files and does not support the deployment of Dockerfiles or any other auxiliary files required by an application.

To deploy a Docker Compose file, follow these instructions:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a meaningful project name and then choose one of the following deployment methods for your Docker Compose file:
   • Editor: This option allows you to directly define or paste the entire content of your Compose file into a web-based text editor.
   • Upload: Use this method to upload a Docker Compose file directly from your local computer's storage.
   • Webspace: Select this option if your Compose file is already stored within a domain’s Home directory. When choosing Webspace, you will first need to select the specific domain where the file is located. Then, for Compose File, browse to and select the exact location of your Compose file within that domain.

Plesk enables you to declare and build custom containers as part of your Docker Compose deployment. Any artifacts generated during this build process will be conveniently placed within the designated website’s Home directory.

For more detailed information concerning the Docker Compose file format and its syntax, please refer to the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is an intuitive and powerful container management software that significantly simplifies the deployment and oversight of containers and stacks. It offers a comprehensive web-based user interface for tasks such as monitoring container status and logs, creating and managing users and teams, and securing your Docker environments, among many other features.

To install Portainer within your Plesk Docker environment, simply navigate to Docker > Install Portainer. Once the installation process is successfully completed, you can access and manage your Portainer containers directly by going to Docker > Go to Portainer.

Note: Portainer integration is currently designated as a beta feature.

For extensive documentation and further details on utilizing Portainer, please visit the official Portainer documentation.