Using Docker | Plesk Obsidian documentation

Docker is a powerful platform designed for running applications within isolated environments called containers. This technology allows users to deploy specific software, such as Redis or MongoDB, or even particular versions of software that might not be natively supported by their operating system or could otherwise require complex compilation processes.

Integrated seamlessly as a Plesk extension, Docker empowers users to efficiently run and manage containers derived from various Docker images. Furthermore, it provides the flexibility to utilize Docker not only on the local host but also across remote servers.

This comprehensive guide will walk you through the essential steps of creating, configuring, and effectively managing Docker containers directly within the Plesk interface. Additionally, you will discover how to control and interact with remote Docker hosts from your Plesk environment, offering extended capabilities and deployment options.

Requirements and Limitations

Warning: The Docker extension directly downloads images from Docker Hub without any preconfiguration. Some Docker containers or the software within them are designed for trusted environments only and may necessitate additional security configurations. Before deploying these downloaded images within Plesk, it is crucial to enhance their security independently. For detailed instructions, always refer to the specific documentation provided by the container or software vendor. For instance, consult the security section in the Redis documentation.

• Docker is officially supported in Plesk on 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 (version 7.0.1-686) or any subsequent updates.
• For Plesk installations on Windows, you have the option to utilize Docker if it is installed on a separate remote machine. Further details can be found in the "Using Remote Docker" section later in this guide.
• It is not possible to run Docker within a Plesk environment that is itself deployed as a Docker container.
• Accessing remote Docker services through Plesk requires an additional license. This license can be acquired either individually or as an integral part of various Plesk offerings, including the Hosting Pack, Power Pack, or Developer Pack.
• Docker operations are restricted to x64 systems exclusively.
• Direct migration or backup of Docker containers within Plesk is not supported. However, it is possible to back up the data utilized by these containers (refer to the "Volume Mapping" section below) or to download container snapshots for preservation.
• Virtuozzo 7, specifically with Update 1 Hotfix 1 (7.0.1-686) or newer, is supported. It's important to note that from this update onwards, new containers based on CentOS 7 are configured with the firewall enabled by default. This change reflects Virtuozzo's enhanced security measures. Consequently, Plesk administrators must 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 operate as the Plesk administrator, you can easily install the extension directly from the Extensions Catalog.
• Conversely, if you are not the administrator, please reach out to your hosting provider and request that they install the extension on your behalf.

Upon successful installation of the extension, you will be prepared to proceed. The "Docker" option will become visible and accessible within the Navigation Pane of your Plesk interface.

Containers

Within Plesk, you can conveniently access a vast array of images from Docker Hub directly within the "Run Container" catalog. This catalog is accessible by navigating to Docker > Containers > Run Container.

Accessing the Container Catalog

To access the Docker image catalog:

• If you have not yet installed any containers, simply navigate to Docker > Containers and click on the Run Container button.
• If you have existing containers, navigate to Docker > Containers and click the plus icon to initiate the creation of a new container.

Once in the catalog, you can utilize the search box to efficiently find available images. You can specify the image name, the repository, or a combination of both to refine your search results.

The available repositories for your search include:

• Local repository: This repository houses images that have already been downloaded and are stored directly on your server, managed by Docker. For more comprehensive information, please refer to the "Managing Local Images" section later in this guide.
• Docker Hub: The official public registry for Docker images.

It is common for multiple versions (or tags) to be available for a single application. You have the flexibility to run a specific version by selecting the appropriate tag during the container creation process.

Running a Docker Container

To initiate and run a new container:

1. Navigate to Docker > Containers > Run Container.
2. Employ the search box to locate the desired image within the catalog. If the image is stored locally, the label (local) will appear next to its version.
3. For images sourced from Docker Hub, you can click the information icon to view a detailed description and access the official documentation on Docker Hub. This option is not applicable to local images.
4. Click on the image card corresponding to the application you wish to deploy.
   • To deploy a specific version of the image, select your desired version from the Image version drop-down menu, then click Next.
   • To deploy the latest available version of the chosen application, simply click Next.

   Plesk will then proceed to create the container and present you with a prompt to define its settings, such as environment variables. After configuration, the container will be launched. You can abort the process at any point by clicking Cancel on the Settings screen. For a detailed breakdown of all available settings, please refer to the "Container Settings" section further down this page.

5. Once you have finalized and adjusted all the necessary settings, click Run. The newly created container will then be listed within the Containers tab, indicating its active status.

To ensure the container is operating correctly and without issues, it is advisable to review the Console Log for any diagnostic messages.

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 modify the settings for a Docker container, navigate to the Containers tab and click the settings icon located next to the specific container you wish to configure.

Limiting Memory Usage

By default, Docker containers operate with unlimited RAM consumption. To impose a memory limit, select the Memory limit checkbox and input the desired limit value, in megabytes, into the corresponding MB field.

Note: Currently, the ability to limit CPU and disk usage for Docker containers is not available within Plesk.

Note: Docker containers are managed as administrator-level objects and are therefore not subject to subscription-level cgroup limits, which typically control CPU, RAM, and disk usage for other services.

Automatic Start Configuration

If the option Automatic start after system reboot is not enabled, then following a system reboot, any websites relying on this container may experience downtime. In such cases, you would be required to manually start the container to restore service.

Port Mapping Management

The Automatic port mapping feature is enabled by default, which means the container’s internal port is automatically mapped to a randomly selected port on the host system (for example, port 32768).

Should you need to assign a specific port on the host system, deselect the Automatic port mapping option and then specify your preferred external port in the Manual mapping field. If the Manual mapping option does not appear after deselecting automatic mapping, it indicates that the container itself does not expose any ports.

When employing manual port mapping, Docker, by default, binds the specified port exclusively to the host system’s localhost interface (127.0.0.1). This configuration ensures that the port remains inaccessible from the public internet, thereby enhancing the security of the application running inside the container by shielding it from external attacks. To allow Docker to bind the specified port to all network interfaces of the host system, you must deselect the Make the port inaccessible from the Internet option. Be aware that doing so will make the application within the container accessible from the internet, reachable via the specified port through any of the host system’s assigned IP addresses.

Warning: Docker typically assumes that authentication for applications is handled internally. However, this is not always the case (e.g., while MySQL/MariaDB generally prohibits anonymous access, Redis permits it by default). 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 for Persistent Storage

Docker volumes represent specific directories on your server that are mounted into a Docker container. This mechanism provides a crucial solution for persistent storage, allowing data to be accessed and retained independently of the container's lifecycle. Critically, data stored within Docker volumes is not deleted when a container is stopped or removed.

Warning: It is imperative to understand that data stored within Docker volumes will not be included in standard Plesk backups. To prevent any potential data loss, it is strongly recommended to back up any 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 into the container.
• In the Container field: Provide the absolute path to the corresponding 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 your setup demands.

Operations with Containers

Plesk provides a comprehensive set of operations for managing your Docker containers effectively:

• You can readily Stop, Start, or Restart any container. It's important to understand that in these scenarios, the container will be recreated utilizing its current settings.

  Note: If you have not configured persistent storage by saving data to mounted volumes (as discussed in the "Volume Mapping" section), any unsaved data within the container will be lost upon these operations.

• To monitor container activity and resource consumption, click the arrow icon positioned next to the container to reveal its logs and usage metrics.
• To modify a container's configuration, such as environment variables or volume mappings, click the settings icon adjacent to the container. This will open the Settings panel.
• You can easily rename a container by accessing its settings (Settings) and then modifying the Container name field.

By clicking the more options icon next to a container, you gain access to additional advanced operations:

• Recreate: This allows you to rebuild a container, either using the identical image version or by selecting a different version from the available catalog.
• Save as Image: Use this function to create a new Docker image based on the current state and custom settings of your container.
• Download Snapshot: This option enables you to take and download a snapshot of your container at a specific point in time.
• Remove: This operation permanently deletes the selected container.

Recreating a Container

The recreation of a container is typically performed when you intend to update the application running within it to a newer version. However, this functionality is versatile, allowing you to rebuild a container using any available application version from the catalog, not exclusively newer ones.

Crucially, all custom settings that you have applied to the container are preserved during the recreation process. To safeguard and ensure the persistence of data utilized by the application inside a container, it is vital to establish volume mapping prior to initiating a container recreation. Volume mapping facilitates access to directories used within a container, as detailed in the "Volume Mapping" section of the container settings.

Steps to Recreate a Container:

1. Navigate to Docker and click the more options icon positioned next to the container you wish to recreate.
2. From the context menu, click Recreate. In the subsequent container settings dialog, you will be prompted to specify the desired image version and to confirm whether to use the default environment variables or your custom ones.

Using Remote Docker

While Plesk defaults to utilizing Docker installed as a local service, it offers the advanced capability to integrate and manage one or more Docker services hosted externally. It's important to note that you can only have one remote Docker service actively connected and managed by Plesk at any given time. The currently active server can always be identified within the "Environments" tab of the Docker settings page in Plesk.

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

Configuring Remote Docker Services

Before you can add a remote Docker server to Plesk, you must configure the remote host itself. Refer to the official Docker documentation for detailed instructions on setting up the remote server to function securely as a remote Docker endpoint in Plesk.

Managing Remote Docker Services

Plesk enables you to establish a secure connection between your Plesk server (equipped with the Docker extension) and a remote node where the Docker service is running.

The following configuration steps are universally applicable for both Plesk for Linux and Plesk for Windows environments.

Steps to Perform on the Remote Host:

1. Create Docker Configuration File: Create the /etc/docker/daemon.json configuration file for Docker 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 TLS Certificate Files: Generate the necessary .pem files for secure communication. You can use the provided example below. Ensure you replace the placeholder IP address (192.0.2.1) on line 4 with the actual IP address of your remote Docker node, and then execute 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. Modify and Restart Docker Service: Execute the following commands to adjust the current Docker service configuration, ensuring it starts correctly after host system reboots and incorporates the new settings:

   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. Save Client Certificate Files: For the client (your local Plesk server) to establish a remote connection, save the outputs of the following files on your local machine:

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

Configuring the Docker Remote Host on the Local Plesk Server:

1. Navigate to Docker > Environments within your Plesk interface.
2. Click the Add Server button and provide the necessary connection settings for your remote Docker server.
3. To immediately begin using this remote Docker service in Plesk, ensure the Set active checkbox remains selected.

Once configured, a dedicated link to this Docker service will appear in the Navigation Pane, allowing for quick access.

Switching Between Docker Services

To alternate between different Docker services (local or remote) that you have configured:

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

Alternatively, you can designate 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 the specific modifications and configurations you have applied to an existing container, the Save as Image command is your essential tool. This operation effectively captures a snapshot of your current container's state, which is then registered as a brand-new image within your Docker image catalog. This method is particularly useful for producing images tailored with custom settings, including unique environment variables.

Steps to Create an Image from an Existing Container:

To initiate the creation of an image from one of your configured containers:

1. Navigate to Docker > Containers.
2. Locate the container from which you wish to create an image, click the more options icon next to it, and then select Save as Image.
3. In the "Save <container name> as Image" side panel that appears, you will need to specify the following details:
   • Image name: Provide a descriptive name for your new custom image.
   • Tag (optional): You can optionally specify a tag to denote the image version. If no tag is provided, the default version will be "latest".

Once created, the new image will be listed in the Images tab, clearly marked as a Local image to indicate its origin and storage location.

Managing Local Images

Local images are Docker images that reside directly on your local disk, eliminating the need to download them from the online Image Catalog each time they are needed. This significantly speeds up deployment and reduces bandwidth usage.

An image transitions to a "local" status under several circumstances:

• When you select any specific version (tag) of an image and its download process begins. Whether you subsequently launch a container from it or cancel the operation on the Settings screen, the image will be stored locally.
• If you explicitly upload an image to Docker within Plesk, using the Upload image function found in the Docker Images tab.
• When you create a custom image directly from an existing container, as described in the "Creating Images with Custom Settings" section.
• Should you build an image via the command-line interface, it will inherently be stored locally.

To acquire 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. This action will download the new version and store it locally.

When at least one version of an image from a particular product group has been downloaded, that image will be designated as a Local image within the catalog. Plesk also conveniently indicates the total number of local images available for each product.

Viewing and Removing Local Images:

To effectively manage your locally stored Docker images, including the removal of outdated ones:

1. Navigate to Docker > Images.
2. Utilize the Search bar to quickly locate a specific local image if needed.
3. To inspect all local images associated with a particular product, click the link situated beneath the product name. This will reveal all local images, their respective tags, and the disk space they currently occupy.
4. Select the specific image(s) you wish to remove from local storage and then click the Remove button.

Setting Up NGINX to Proxy Requests from Domains to a Container

Many Docker containers are designed to expose specific ports, allowing the applications running within them to be accessible via those ports. However, when integrating such an application with your website, requiring users to specify a non-standard port in the URL can be cumbersome and unprofessional.

To circumvent this inconvenience, you can configure NGINX to proxy incoming requests from your domains to the specific container port. This setup enables your domains to operate on standard web ports (such as 80 for HTTP or 443 for HTTPS), eliminating the need for users to explicitly include the port number in the URL.

Requirements for NGINX Proxy Setup:

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

Steps to Manually Map a Container Port:

1. Navigate to Docker > Containers and click the settings icon next to the container you intend to configure.
2. Deactivate the Automatic port mapping option.
3. Manually assign the container's internal port to a distinct port on your host system (e.g., 32768). For enhanced security, you have the option to make this host port inaccessible from the public internet.

Once the container port is manually mapped, you can proceed to configure NGINX to act as a proxy. This allows your domains to use a standard port (like 80) on NGINX, forwarding requests seamlessly to your Docker container. To enable this, you must add a specific proxy rule within your domain's settings.

Adding an NGINX Proxy Rule in Domain Settings:

To establish an NGINX proxy rule for your domain:

1. Go to Websites & Domains > [select your domain] > Docker Proxy Rules > Add Rule.
2. In the configuration panel, specify the following details:
   • URL: Define the URL of your website, or a specific part of it, that will utilize the application running within the Docker container.
   • Container: Select the Docker container that hosts the application you wish to proxy to.
   • Port: Choose one of the port mappings previously defined in the container's settings (specifically, the internal container port mapped to a port on your host system). NGINX will then intelligently proxy incoming requests to this designated host system port.

These proxy rules are intricately integrated into the web server's configuration, typically found within the website’s nginx.conf file (located in /var/www/vhosts/system/$domain/conf/). An example of such a configuration block 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 worth noting that proxy rules are generally designed to function effectively even on servers positioned behind Network Address Translation (NAT).

Note: Docker containers that are connected to a website via Proxy Rules typically do not contribute to the subscription's calculated disk space usage. An exception arises when a website directory is mounted into a Docker container as a volume; in this specific scenario, all files located within that container will indeed be factored into the website's total disk space consumption.

Deploying Docker Compose YAML Files

Plesk provides versatile options for deploying your Docker Compose YAML files, catering to various workflows. You can utilize an integrated online text editor, upload a file directly from your local storage, or select a Docker Compose file that is already stored within a website's Home directory. Plesk supports standard operations on Docker Compose stacks, including up (which encompasses pull and force-recreate), stop, and down. Furthermore, you retain the flexibility 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 deploy Dockerfiles or other application-specific files using these methods.

Steps to Deploy a Docker Compose File:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a unique project name for your Docker Compose deployment. Following this, select one of the available methods for deploying your Docker Compose file:
   • Editor: This option allows you to directly define or paste the content of your Compose file into an online text editor within Plesk.
   • Upload: Choose this method to upload a Docker Compose file from your local computer's storage.
   • Webspace: If your Docker Compose file is already stored within a domain’s Home directory, select this option. You will then need to choose the specific domain where the file is located and browse to the Compose file's exact location.

Within your Docker Compose files, you have the capability to declare and build custom containers. Any artifacts generated during this build process, such as images or temporary files, will be conveniently placed inside the website’s Home directory associated with the stack.

For in-depth information regarding the syntax and structure of the Compose file format, please consult the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is an intuitive and powerful container management software designed to simplify the deployment of containers and stacks, provide clear visibility into container status and logs, facilitate the creation of users and teams, and enhance the security of your Docker environments, among many other features.

Installing and Accessing Portainer:

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

Note: It is important to be aware that Portainer is presently offered as a beta feature within Plesk.

For a comprehensive understanding of Portainer's capabilities and functionalities, please refer to the official Portainer documentation.