Using Docker in Plesk Obsidian

This guide provides comprehensive instructions on leveraging Docker within Plesk Obsidian. Docker, a powerful platform for containerized applications, allows you to deploy and manage specific software—such as Redis or MongoDB—or particular software versions that might not be natively supported by your operating system or require complex compilation processes. Available as a Plesk extension, Docker facilitates the seamless execution and management of containers built from various Docker images, supporting operations on both local and remote host environments. Throughout this document, you will discover how to efficiently create, configure, and manage Docker containers in Plesk, alongside detailed procedures for controlling remote Docker hosts directly from your Plesk interface.

Requirements and Limitations

Warning: The Docker extension downloads images from Docker Hub as they are, without any pre-configuration. Some Docker containers or the software within them are intended for trusted environments only and may necessitate additional security setups. Before launching these downloaded images in Plesk, it is crucial to enhance their security independently. For specific instructions, always refer to the documentation provided by the container or software vendor. For instance, you can consult the security section in the Redis documentation for guidance.

• Docker is supported in Plesk for a wide 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. Please note that for Plesk on Windows, Docker must be installed and managed on a remote machine.
• It is not possible to utilize Docker within a Plesk instance that is itself deployed in a Docker container.
• To access and manage remote Docker services from Plesk, an additional license is required. This license can be acquired separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker is exclusively designed to run on x64 systems.
• Direct migration or backup of Docker containers within Plesk is not supported. However, you can back up the data utilized by these containers through volume mapping (as detailed in the "Volume Mapping" section below) or by downloading container snapshots.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or a later version is fully supported. It is important to note that with this update, new CentOS 7-based containers are created with the firewall enabled by default, reflecting Virtuozzo's enhanced security measures. Plesk administrators must manually configure the firewall to ensure that all necessary ports for Plesk operations are open.

Prerequisites

Before you can begin utilizing Docker functionalities, the Docker extension must be successfully installed on your Plesk server. Follow these guidelines:

• If you are the Plesk administrator, you can install the extension directly from the Extensions Catalog within Plesk.
• Otherwise, please contact your hosting provider and request that they install the Docker extension for you.

Once the extension is installed and activated, you are ready to proceed. The "Docker" option will become visible and accessible in the Plesk Navigation Pane, indicating successful setup.

Containers

You can readily access a vast array of images from Docker Hub directly within the Run Container catalog, which can be found by navigating to Docker > Containers > Run Container.

To access the catalog and begin selecting images:

• If you have not previously installed any containers, simply click Run Container in the Docker > Containers section.
• If you have installed containers before, click the plus icon to access the catalog.

To view available images, utilize the integrated search box:

You can specify either the image name, the repository, or both to refine your search results.

The following repositories are available for searching:

• Local repository: This contains images that have already been downloaded and are currently stored on your server with Docker. For more details, refer to the "Managing Local Images" section later in this document.
• Docker Hub: The official public registry for Docker images.

Multiple versions of each application may be available. You can run a specific version by carefully selecting the appropriate tag from the dropdown menu, as illustrated below:

To run a container using a selected image:

1. Navigate to Docker > Containers > Run Container.
2. Use the search box to locate desired images within the catalog. If an image is already stored locally on your server, "(local)" will be indicated after its version.
3. To view the image's description and detailed documentation on Docker Hub, click the more info icon . This option is not applicable for local images.
4. Click on the image card to proceed.
   • To run a specific image version, select your desired 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.
   Plesk will then initiate the container creation process and prompt you to specify its settings, such as environment variables, before running it. You have the option to cancel this process by clicking Cancel on the Settings screen. For comprehensive information regarding these settings, please refer to the "Container Settings" section further down this page.
5. After adjusting the settings as needed, click Run. The newly created container will then appear in the list within the Containers tab, indicating it is operational.

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

Container Settings

Note: You do not need to stop a container to modify its settings. When you save new configurations, Plesk intelligently recreates the container with the updated parameters, ensuring minimal downtime.

To adjust or edit container settings, navigate to the Containers tab and click the settings icon located next to the specific container you wish to modify.

Limiting Memory

By default, Docker containers operate with an unlimited amount of RAM. To impose a memory constraint, select the Memory limit checkbox and input your desired limit value in megabytes within the MB field. This helps manage resource consumption on your host system.

Note: At present, CPU and disk usage cannot be directly limited for Docker containers through this interface. Docker containers are treated as administrator-level objects and are not governed by subscription-level cgroup limits for CPU, RAM, or disk usage.

Automatic Start

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

Port Mapping

Initially, Automatic port mapping is enabled, which means the container's internal port is automatically mapped to a randomly assigned port on the host system (e.g., 32768).

To change the port on the host system to a specific one, deselect Automatic port mapping and then specify an alternative external port in the Manual mapping field. If the Manual mapping option does not appear after deselection, it indicates that the container does not expose any ports.

When employing manual mapping, Docker by default only binds to the specified port on the host system’s localhost interface (127.0.0.1). This configuration inherently makes 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 advised that doing so will make the application inside the container accessible from the Internet via any of the host system’s IP addresses on the designated port.

Warning: Docker typically assumes that authentication is handled by the application itself. However, this is not always the case (e.g., MySQL/MariaDB restricts anonymous access by default, while Redis does not). Making the application within a container internet-accessible without proper authentication mechanisms can expose it to malicious actors and potential security vulnerabilities.

Volume Mapping

Docker volumes represent directories on your server that are mounted into a Docker container. This mechanism provides persistent storage, allowing data to persist independently of the container's lifecycle and be accessible from your host system. Data stored within Docker volumes remains intact even when you stop or delete a container.

Warning: It is crucial to understand that data stored in Docker volumes will not be automatically included in Plesk backups. To prevent any data loss, it is highly recommended to back up any essential data residing in a volume using a third-party backup solution.

For more in-depth information regarding data management in 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 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 vital for configuring the application running inside a container. You may need to add new variables or modify existing ones to tailor the application's behavior. Plesk offers the flexibility to add as many environment variables as your application requires.

Operations with Containers

Plesk offers a suite of operations to effectively manage your Docker containers:

• You can effortlessly stop (Stop), start (Start), or restart (Restart) any container. In each of these scenarios, the container will be recreated with its current settings.

  Note: If you have not saved critical data to mounted volumes (refer to the "Volume Mapping" section), this data will be lost upon recreation.

• To access detailed logs and monitor resource consumption, click the arrow positioned next to the container.
• Modify container settings, such as environment variables or volume mapping, by clicking the settings icon adjacent to the container.
• Rename a container by navigating to its settings (Settings > Container name).

For additional advanced operations, click the more options icon next to the container. This menu allows you to:

• Recreate a container, either using the existing image version or a different one (Recreate).
• Create a new image based on your customized container settings (Save as Image).
• Capture a snapshot of your container's current state (Download Snapshot).
• Permanently remove a container (Remove).

Recreating a Container

Recreating a container is typically necessary when you need to update the application it hosts 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. All custom settings applied to the container are carefully preserved during the recreation process. To ensure the preservation of data used by the application within the container, it is essential to establish volume mapping before initiating a recreation. Volume mapping grants you persistent access to the directories utilized inside a container, as detailed in the Volume Mapping section within container settings.

To recreate a container effectively:

1. Go to Docker and click the more options icon located next to the container you wish to recreate.
2. Click Recreate within the container settings. You will then be prompted to specify the desired image version and to confirm whether to use default environment variables or your custom ones.

Using Remote Docker

By default, Plesk utilizes Docker installed as a local service on the same server. However, for increased flexibility, you have the option to integrate one or more external Docker services. It's important to note that only one remote Docker service can be active at any given time. The currently active server can be identified in the "Environments" tab of the Docker settings page within 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 Services

To prepare a remote server running Docker for integration with Plesk, configure it as described in the official Docker documentation on daemon socket options to enable its use as a remote server in Plesk.

Managing Remote Services

You can establish and manage a secure connection between your Plesk server (with the Docker extension installed) and a remote node hosting a Docker service. The following detailed steps are applicable for both Plesk for Linux and Plesk for Windows environments.

Perform these steps on the remote host where Docker is running:

1. Create the /etc/docker/daemon.json configuration file for Docker with the following content. This configuration enables TLS and specifies the necessary certificate paths for secure communication:

   	{ "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 essential .pem files for TLS communication. You can utilize the following example to generate these files. Remember to replace the IP address 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. 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. Save the outputs of the following files from your remote machine to your local machine. These files are necessary for the client (Plesk) to establish a secure remote connection:

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

Now, on the local Plesk server, configure the Docker remote host:

1. Navigate to Docker > Environments.
2. Click Add Server and input the connection settings for the remote server running Docker, including the certificates obtained in the previous step.
3. To immediately begin using this specific Docker service within Plesk, ensure that Set active remains selected.

Once configured, the link to the active Docker service will appear conveniently in the Navigation Pane.

To switch between different Docker services (local or remote):

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

Alternatively, you can also set a Docker node as active directly while editing its settings.

Creating Images with Custom Settings

If you have made modifications to a container and wish to save those changes as a new, reusable image, utilize the Save as Image command. This operation essentially captures a snapshot of your customized container, which then appears as a new image in your image catalog. This feature is particularly useful for creating images with specific configurations, such as custom environment variables, tailored to your application's needs.

To create a new image from one of your existing containers:

1. Navigate to Docker > Containers.
2. Click the more options icon next to the container from which you want to create an image, and then click Save as Image.
3. In the Save <container name> as Image side panel, you will need to specify:
   • The desired Image name.
   • An optional Tag, which can be used to denote the image version. By default, if no tag is provided, the version will be set as “latest”.

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

Managing Local Images

Local images are Docker images that are stored directly on your local disk, eliminating the need to download them repeatedly from the online Image Catalog. This optimizes deployment times and reduces reliance on external network connectivity.

An image becomes a local image under the following circumstances:

• You have selected any version (tag) of an image, and the download process has commenced. Even if you later run a container or cancel the operation on the "Settings" screen, the image data will be saved locally.
• You have manually uploaded an image to Docker in Plesk via the Upload image option in the Docker Images tab.
• You have successfully created a custom image based on an existing container (as detailed in the "Creating Images with Custom Settings" section).
• You have built an image using the command-line interface directly on the server.

To download an additional version of an image from the online catalog, click the Pull icon , select the specific version you wish to pull from the drop-down menu, and then click Pull.

If Docker has at least one downloaded version belonging to a group of images, that image will be labeled as a Local image in the catalog. Plesk also conveniently displays how many local images exist for a particular product.

To efficiently view and remove outdated or unnecessary local images:

1. Navigate to Docker > Images.
2. To quickly locate a specific local image, use the integrated Search bar.
3. To view all local images associated with a particular product, click the link situated under the product name. This action will display all local images' tags and the 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 accessible externally via those ports. When integrating an application running in a Docker container with your website, it can be cumbersome for users to remember and specify a non-standard port in the URL.

To enhance user experience and simplify access, you can configure Nginx to proxy requests from your domains to the container's exposed port. This setup allows your domains to use standard web ports (such as 80 or 443) without requiring users to explicitly include the port number in the URL.

Requirements

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

To manually map the port inside a container:

1. Go to Docker > Containers and click the settings icon next to the container you wish to configure.
2. Disable the Automatic port mapping option.
3. Manually map the internal port of the container to a specific port on your host system (for instance, 32768). You have the option to make this 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 specified port on the host system. To achieve this, add a new rule within the domain's settings.

To add a proxy rule for Nginx in the domain settings:

1. Navigate to Websites & Domains > your specific domain > Docker Proxy Rules > Add Rule.
2. Specify the following details for the new rule:
   • URL: Define the URL of the website or a specific path within it that utilizes the application running in the Docker container. This can be the main website or a particular section.
   • Container: Select the Docker container hosting the application you wish to proxy.
   • Port: Choose one of the port mappings previously defined in the container's settings (i.e., the internal container port mapped to a port on your host system). Nginx will then proxy incoming requests to this designated port on the host system.

These proxy rules are implemented directly within the web server configuration, typically found in the website’s nginx.conf file (located at /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;
}
#extension docker end

It is worth noting that these proxy rules are designed to function seamlessly even on servers operating behind Network Address Translation (NAT).

Note: Docker containers connected to a website via Proxy Rules are generally not included in the subscription’s disk space usage calculations. An exception occurs if a website directory is mounted into a Docker container as a volume; in this specific scenario, all files located within that container will be accounted for in the website's disk space usage.

Deploying Docker Compose YAML files

Plesk provides a streamlined way to deploy applications defined by Docker Compose YAML files. You can deploy these files using an online text editor, by uploading a file from your local storage, or by selecting a Docker Compose file already stored within a website’s Home directory. Standard Docker Compose operations, such as up (which includes pull and force-recreate), stop, and down, are fully supported. Furthermore, you retain the ability to modify and update your deployed stacks after their initial creation.

Note: This particular section is specifically for deploying Docker Compose YAML files and does not support the deployment of Dockerfiles or any other application-specific files.

To deploy a Docker Compose file:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a project name for your stack and then choose one of the following methods for deploying your Docker Compose file:

   • Editor: Directly define or paste the content of your Docker Compose file into the provided text editor.
   • Upload: Upload a Docker Compose file from your local storage.
   • Webspace: Select an existing Docker Compose file that is stored within a domain’s Home directory. If choosing this option, you will need to select the specific domain where the file is located and then browse to the Compose file's exact location.

You have the flexibility to declare and build custom containers as part of your Docker Compose deployment. Any artifacts generated during the build process will be conveniently placed within the associated website’s Home directory.

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

Deploying Portainer Containers in Docker

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

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

Note: Portainer integration within Plesk is currently considered a beta feature, and its functionality may be subject to further development and refinement.

For extensive information and guidance on using Portainer, please consult the official Portainer documentation.