Using Docker in Plesk Obsidian

Docker is an advanced platform designed for deploying and managing applications within isolated containers. This technology allows users to leverage specific software, such as Redis or MongoDB, or particular software versions that might not be natively supported by their operating system or could require complex compilation processes. Docker provides an efficient and portable solution for software deployment.

Integrated seamlessly as a Plesk extension, Docker empowers you to effortlessly run and manage containers derived from various Docker images. This functionality extends to both local host environments and remote servers, offering remarkable flexibility.

This comprehensive guide will walk you through the essential steps to create, configure, and effectively manage Docker containers directly within the Plesk interface. Furthermore, it will cover the procedures for controlling and integrating remote Docker hosts with your Plesk environment, ensuring a robust and scalable infrastructure.

Requirements and Limitations

Important Warning: The Docker extension facilitates the direct download of images from Docker Hub without any pre-configuration. It is crucial to understand that some Docker containers and the software they encapsulate are designed for trusted environments only and may necessitate additional security configurations. Before initiating these downloaded images within Plesk, you are solely responsible for enhancing their security. For detailed guidance, always refer to the official documentation provided by the container or software vendor. For instance, you can consult the security section in the Redis documentation for specific recommendations.

• Docker is officially supported in Plesk 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 (version 7.0.1-686) or any subsequent updates.

  For Plesk on Windows installations, you have the option to utilize Docker deployed on a remote machine. Refer to the section on Using Remote Docker later in this guide for detailed instructions.

• It is not possible to run Docker within a Plesk instance that is itself deployed inside a Docker container.
• Accessing remote Docker services through Plesk requires an additional license. This can be acquired separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker functionality is exclusively available on x64 architectures.
• Direct migration or backup of Docker containers within Plesk is not supported. However, you can secure the data utilized by your containers by configuring Volume Mapping (detailed below) or by downloading container snapshots.
• Virtuozzo 7 with Update 1 Hotfix 1 (version 7.0.1-686) or later is fully supported. Please note that with this update, newly created CentOS 7-based containers have their firewall enabled by default, reflecting Virtuozzo's commitment to enhanced security. Plesk administrators must therefore manually configure the firewall to ensure that all ports essential for Plesk's operation are open.

Prerequisites

Prior to leveraging Docker's capabilities, it is imperative that the Docker extension is properly installed on your Plesk server. This foundational step ensures that all Docker functionalities are available within your Plesk environment.

• If you possess Plesk administrator privileges, you can easily install the extension directly from the Extensions Catalog.
• Should you not have administrator access, please reach out to your hosting provider and request that they install the Docker extension on your behalf.

Upon successful installation of the extension, you will be prepared to commence using Docker. The "Docker" option will become visible and accessible within the Navigation Pane of your Plesk interface, signifying its readiness for use.

Containers

Plesk allows you to seamlessly access and deploy images directly from Docker Hub through the Run Container catalog. This catalog is accessible via Docker > Containers > Run Container.

Accessing the Container Catalog

To navigate to the container catalog and explore available images:

• If you are new to Docker in Plesk and have not yet installed any containers, simply go to Docker > Containers and click the Run Container button.
• For users who have previously deployed containers, the catalog can be accessed by navigating to Docker > Containers and clicking the plus icon (representing "Add New Container").

Once in the catalog, you can efficiently locate desired images by utilizing 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 queries:

• Local repository: This repository houses images that have already been downloaded and are currently stored on your server, managed by Docker. For more detailed information, please refer to the section on Managing Local Images further within this guide.
• Docker Hub: The vast public registry for Docker images, offering a wide array of official and community-contributed images.

It is common for multiple versions of a particular application to be available. You have the flexibility to deploy a specific version by simply selecting the corresponding tag.

Steps to Run a Container

Follow these steps to successfully run a Docker container in Plesk:

1. Navigate to Docker > Containers > Run Container to access the image catalog.
2. Utilize the search box to find the desired images within the catalog. If an image is already present on your local system, it will be indicated by (local) appended after its version number.
3. For images sourced from Docker Hub, you can view their comprehensive description and official documentation by clicking the more info icon. This option is not applicable to locally stored images.
4. Click on the image card representing the application you wish to deploy.
   • To deploy a specific version of the image, select your preferred version from the Image version drop-down menu, then click Next.
   • Alternatively, to run the latest available version of the selected application, simply click Next.

   Plesk will then proceed to create the container. You will be prompted to define its specific settings, such as environment variables, before the container is initiated. If you decide not to proceed, you can cancel the operation by clicking Cancel on the Settings screen. For a comprehensive understanding of these configuration options, consult the Container Settings section provided later on this page.

5. After meticulously adjusting the settings to meet your requirements, click Run. The newly launched container will then appear in the list of containers in the Containers tab.

It is recommended to check the Console Log to verify that the container is operating as expected and without any issues.

Container Settings

Note: When adjusting container settings, there is no need to stop the running container. Plesk automatically recreates the container with the newly saved settings, ensuring a smooth update process.

To modify the settings of any container, navigate to the Containers tab and click the settings icon adjacent to the container you wish to configure.

Limiting Memory Usage

By default, Docker containers operate without any predefined RAM limits, allowing them to utilize available system memory as needed. To impose a specific memory restriction, simply select the Memory limit checkbox and input your desired limit value in megabytes (MB) into the corresponding field.

Note: At present, resource limitations for CPU and Disk usage are not supported for Docker containers within Plesk.

Important: Docker containers are treated as administrator-level objects within Plesk and are therefore not governed by subscription-level cgroup limits, which typically control CPU, RAM, and Disk usage for other services.

Automatic Start Configuration

The "Automatic start after system reboot" option determines whether your container will automatically restart following a system reboot. If this option is not enabled, any websites or services relying on this container might become unavailable after a system restart, requiring manual intervention to start the container.

Port Mapping

Initially, Automatic port mapping is enabled, which means the container’s internal port is automatically mapped to a randomly assigned, available port on the host system (e.g., 32768). This default behavior simplifies initial setup.

To customize the port on the host system, deselect the Automatic port mapping option. You can 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 is not configured to expose any ports.

When utilizing manual mapping, Docker typically binds the specified port exclusively to the host system’s localhost interface (127.0.0.1) by default. This configuration ensures that the port remains inaccessible from the public internet, thereby enhancing the security of the application residing within the container. To enable Docker to bind the specified port to all network interfaces on the host system, deselect the Make the port inaccessible from the Internet option. Choosing this will make the application inside the container reachable from the internet on the specified port via any of the host system’s IP addresses.

Security Warning: Docker generally assumes that authentication mechanisms are handled by the application itself. However, this is not always the case (e.g., while MySQL/MariaDB typically requires authentication, Redis might not by default). Exposing an application within a container to the internet without proper authentication and security measures can significantly increase its vulnerability to malicious attacks. Exercise caution and ensure robust security practices are in place.

Volume Mapping

Docker volumes represent directories on your server that are strategically mounted to a Docker container. This mechanism is fundamental for achieving persistent storage that can be reliably accessed from your host system. A significant advantage of Docker volumes is that the data they contain remains intact even when you stop or delete a container, preventing data loss.

Important Note: Data stored within Docker volumes will not be automatically included in Plesk's native backup processes. To safeguard essential data, it is strongly recommended to implement a third-party backup solution for any critical information residing in a volume.

For a more in-depth understanding of data management within containers, please consult the official Docker documentation on volumes.

To establish a volume mapping, you need to specify two key paths:

• 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: Specify the absolute path to the corresponding directory inside the Docker container.

Should you require additional directory mappings, simply click Add one more to include more volume configurations.

Setting Environment Variables

Environment variables play a crucial role in configuring the application running inside a container. You may find it necessary 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 demands, providing granular control over its operational parameters.

Operations with Containers

Plesk provides a comprehensive suite of tools for managing your Docker containers effectively. You can perform various essential operations directly from the interface:

• Managing Container State: You have the ability to explicitly Stop, Start, or Restart any given container. It is important to note that performing these actions will result in the container being recreated with its current configuration settings.

  Important Note: Be aware that if your application data has not been persisted to mounted volumes (as discussed in the Volume Mapping section), this data will be permanently lost when the container is recreated.

• Monitoring and Diagnostics: To gain insights into your container's performance and operational status, click the arrow icon situated next to the container. This action will reveal detailed logs and real-time resource consumption metrics.
• Adjusting Settings: To modify the configuration parameters of a container, such as environment variables or volume mappings, click the settings icon. This will open the Settings panel for that specific container.
• Renaming Containers: You can easily rename a container for better organization by navigating to its Settings and modifying the Container name field.

For more advanced actions, click the more options icon next to the desired container. This menu provides access to additional functionalities, including:

• Recreate: Rebuild the container, either with the existing image version or by selecting a different one.
• Save as Image: Generate a new Docker image from the current state of your container, incorporating any custom modifications you have made.
• Download Snapshot: Capture a snapshot of your container at a specific point in time, allowing for later restoration or analysis.
• Remove: Permanently delete the container from your Plesk environment.

Recreating a Container

Container recreation is a common procedure, primarily undertaken when updating an application 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.

A key advantage of the recreation process is that all your custom container settings are meticulously preserved. To ensure the integrity of data utilized by the application within the container, it is critical to configure Volume Mapping prior to initiating a container recreation. Volume mapping provides persistent access to directories used internally by the container, safeguarding your valuable data.

To recreate a container, follow these steps:

1. Navigate to Docker and locate the container you wish to recreate. Click the more options icon adjacent to it.
2. From the menu that appears, click Recreate. You will then be prompted to specify the desired image version and confirm whether to utilize the default environment variables for the new container instance.

Using Remote Docker

While Plesk inherently utilizes Docker installed as a local service, it offers the flexibility to integrate and manage one or more Docker services hosted externally. It is important to remember that only one Docker service can be active within Plesk at any given time. The currently active server can be easily identified in the Environments tab of the Docker settings page within Plesk.

Note: Management of remote Docker services is an advanced feature that necessitates a specific Plesk license key add-on. Without this add-on, your capabilities will be restricted to managing only the local Docker service that operates directly on the Plesk server.

Configuring Remote Services

To successfully integrate a remote Docker server with Plesk, you must first configure the remote host as outlined in the official Docker documentation, specifically focusing on secure communication (HTTPS) setup. This foundational configuration is essential for establishing a reliable connection.

Managing Remote Services

The process of establishing a secure connection between your Plesk server (equipped with the Docker extension) and a remote node running the Docker service is straightforward. These instructions are applicable for both Plesk on Linux and Plesk on Windows environments.

The initial steps must be executed on the remote host where Docker is installed:

1. Create Docker Configuration File: Construct the /etc/docker/daemon.json configuration file for Docker, populating it with the following JSON content. This file configures Docker to listen for remote connections securely using 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 TLS Certificate Files: Generate the necessary .pem files for TLS authentication. The following example script can be used. Remember to replace the placeholder IP address on line 4 (/CN=192.0.2.1) with the actual IP address of your remote Docker node. 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. Configure Docker Service for Persistence: Execute the following commands to modify the Docker systemd service configuration, ensuring that Docker starts automatically and correctly after a host configuration change or system reboot:

   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 Authentication Files: On your local machine (the Plesk server), securely save the contents of the following files. These will be used by the Plesk client to authenticate and connect to the remote Docker host:

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

Now, proceed to your local Plesk server to configure the Docker remote host:

1. Access the Docker settings by navigating to Docker > Environments.
2. Click the Add Server button and provide the necessary connection details for your remote Docker server.
3. To immediately activate and begin using this remote Docker service within Plesk, ensure that the Set active option remains selected during configuration.

Once successfully added, a direct link to the Docker service will appear conveniently in the Navigation Pane of your Plesk interface.

Switching Between Docker Services

If you have configured multiple Docker services (both local and remote), you can easily switch between them:

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

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

Creating Images with Custom Settings

For scenarios where you have made specific modifications or configurations within a running container and wish to immortalize these changes into a new, reusable image, the Save as Image command is invaluable. This function captures the current state of your container, effectively creating a snapshot that then appears as a distinct new image within your Plesk image catalog. This capability empowers you to generate customized images pre-configured with bespoke settings, including unique environment variables.

Steps to Create an Image from a Container

To create a new Docker image from an existing container:

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 contextual menu, select Save as Image.
4. A side panel titled "Save <container name> as Image" will appear, prompting you to specify the following details:
   • Image name: Provide a descriptive name for your new custom image.
   • Tag (optional): You can specify an optional tag, which typically denotes the image version. If no tag is provided, the default version will be "latest".

Once saved, the newly created image will be listed in the Images tab and distinctly marked as a Local image, indicating its origin and local storage.

Managing Local Images

Local images are Docker images that reside directly on your server's local disk. Their presence locally eliminates the need for repeated downloads from external repositories like the Docker Image Catalog, thereby saving bandwidth and accelerating deployment times.

When Does an Image Become Local?

A Docker image transitions to a local status under several common scenarios:

• When you initiate a download for any version (tag) of an image, and the download process begins. Whether you subsequently run a container based on it or cancel the operation from the Settings screen, the image file is retained locally.
• If you explicitly upload an image to Docker within Plesk using the Upload image function found in the Docker Images tab.
• When you successfully create a customized image from an existing container instance, as detailed in the section Creating Images with Custom Settings.
• If an image is built directly on your server using the Docker command-line interface.

To download an alternative version of an image from the online catalog, simply click the Pull icon. From the subsequent drop-down menu, select your desired version and confirm by clicking Pull.

In the catalog, an image is designated as a Local image if at least one of its associated versions has been downloaded. Plesk further enhances visibility by indicating the total number of local images available for a particular product.

Viewing and Removing Local Images

To effectively manage your local Docker images and free up disk space by removing outdated versions, follow these steps:

1. Navigate to Docker > Images within your Plesk interface.
2. Utilize the Search bar to quickly locate a specific local image if needed.
3. To view all local images pertaining to a particular product, click the link displayed directly beneath the product's name. This action will present a detailed list, showing all local image tags and the corresponding disk space each occupies.
4. Select the specific image(s) you wish to remove from your 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 designated network entry points.

When integrating a Dockerized application into your website, directly specifying a non-standard port in the URL can be cumbersome for users. To enhance user experience and simplify access, you can configure Nginx to act as a reverse proxy. This setup enables your domains to utilize standard web ports (such as port 80 or 443), while Nginx intelligently forwards requests to the application's non-standard port within the Docker container, thereby eliminating the need for explicit port specification in the URL.

Prerequisites for Nginx Proxy Setup

Before proceeding with Nginx proxy configuration, ensure the following conditions are met:

• 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 (e.g., 32768). This manual mapping is a crucial step for Nginx to identify the correct target port.

Mapping the Port Inside a Container

To establish the necessary port mapping:

1. Navigate to Docker > Containers and click the settings icon corresponding to the container you intend to configure.
2. Deactivate the Automatic port mapping option.
3. Proceed to manually map the container's internal port to a distinct port on your host system (for example, port 32768). During this step, you have the option to configure this host port to be inaccessible from the public internet, adding an extra layer of security.

Once the container's port is manually mapped, you can then 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., port 80). To enable this functionality, you will need to add a dedicated rule for Nginx within your domain's settings.

Adding an Nginx Proxy Rule in Domain Settings

Follow these steps to add a new Nginx proxy rule:

1. Go to Websites & Domains.
2. Select the specific domain for which you want to configure the proxy rule.
3. Navigate to Docker Proxy Rules and click Add Rule.
4. Specify the following parameters:
   • URL: Define the URL of your website that will utilize the application running within the Docker container. This can be the main domain URL or a specific subdirectory.
   • Container: From the dropdown list, select the Docker container hosting the application you wish to proxy to.
   • Port: Choose one of the port mappings that you previously configured in the container settings (specifically, the host system port mapped to the container's internal port). Nginx will then proxy incoming requests to this designated port on your system.

These proxy rules are intricately integrated into the web server configuration, typically found in the website’s nginx.conf file (located at /var/www/vhosts/system/$domain/conf/). An example of such a configuration snippet is provided 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 Nginx proxy rules are designed to function effectively even on servers situated behind Network Address Translation (NAT) environments.

Important Note: Docker containers that are connected to a website via Proxy Rules typically do not contribute to the subscription’s overall disk space usage. An exception arises if a website directory is mounted directly into a Docker container as a volume; in such instances, all files residing within that container will be factored into the website’s reported disk space consumption.

Deploying Docker Compose YAML Files

Plesk streamlines the deployment of complex, multi-container Docker applications by supporting Docker Compose YAML files. You have several convenient options for deploying these files: directly using an online text editor, uploading a file from your local storage, or selecting an existing Docker Compose file already present within a website’s Home directory.

Common Docker Compose stack operations are fully supported, providing comprehensive control over your deployments. These include up (which encompasses pull for fetching images and force-recreate for rebuilding services), stop for gracefully halting services, and down for dismantling the entire stack. Furthermore, Plesk allows you to modify and seamlessly update your Docker Compose stacks even after their initial creation.

Important Note: This section is specifically designed for deploying Docker Compose YAML files. It does not support the deployment of Dockerfiles or any other auxiliary files required by an application directly.

Steps to Deploy a Docker Compose File

To deploy your Docker Compose configuration, follow these steps:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a descriptive project name for your Docker Compose stack. Subsequently, select one of the following methods for deploying your docker-compose file:
   • Editor: This option allows you to directly define or paste the entire content of your Docker Compose file into an integrated online text editor.
   • Upload: Choose this method to upload a docker-compose file directly 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 specify the domain where the file is located, and subsequently browse to the exact location of your Compose File within that domain's structure.

With Docker Compose, you can also declare and build custom containers directly within your configuration. Any build artifacts generated during this process will be conveniently placed inside the respective website’s Home directory.

For comprehensive details on the structure and syntax of the Docker Compose file format, please refer to the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a powerful and intuitive container management software designed to simplify the deployment of individual containers and complex stacks. It provides a user-friendly web interface that streamlines various administrative tasks, including viewing container status and logs, managing user access and teams, and securing your Docker environments, among many other functionalities.

Installing and Accessing Portainer

To install Portainer within your Plesk Docker environment:

1. Navigate to Docker > Install Portainer.
2. Once the installation process is successfully completed, you can access and manage your Portainer containers by going to Docker > Go to Portainer.

Note: At the current time, Portainer integration within Plesk is designated as a beta feature. Users should be aware that features marked as beta may be subject to changes or refinements.

For a complete understanding of Portainer's extensive features and capabilities, please consult the official Portainer documentation.