Using Docker in Plesk Obsidian

Docker is a powerful platform designed for running applications in isolated containers. This technology allows you to deploy specific software, such as Redis or MongoDB, or even particular versions of software that might otherwise be incompatible with your operating system or require complex compilation processes.

Within Plesk, Docker is seamlessly integrated as an extension. This integration empowers you to efficiently run and manage containers derived from various Docker images, utilizing Docker services on both your local host and interconnected remote servers.

This comprehensive guide will walk you through the essential steps of creating, configuring, and effectively managing Docker containers directly within the Plesk environment. Furthermore, you will learn how to extend your control to remote Docker hosts, expanding your deployment capabilities.

Requirements and Limitations

Warning: The Docker extension directly downloads images from Docker Hub without any preconfiguration. Some Docker containers or their embedded software are designed solely for trusted environments and may necessitate additional security configurations. It is crucial to enhance the security of these downloaded images yourself before launching them within Plesk. For precise instructions, always refer to the official documentation provided by the container or software vendor. For instance, consult the security section in the Redis documentation for detailed guidance.

• 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 (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 remote machine, as detailed later in this guide under the section "Using Remote Docker".
• It is important to note that Docker cannot be used within a Plesk instance that is itself deployed inside a Docker container.
• Accessing remote Docker services through Plesk necessitates 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 is exclusively compatible with x64 systems.
• Direct migration or backup of Docker containers within Plesk is not supported. However, you can back up data utilized by these containers (refer to the "Volume Mapping" section below) or download snapshots for recovery purposes.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later is supported. Please be aware that starting with this update, new CentOS 7-based containers are created with the firewall enabled by default, a measure implemented by Virtuozzo to enhance security. Consequently, a Plesk administrator must manually configure the firewall to ensure all necessary ports for Plesk operations are open.

Prerequisites

Before you can begin leveraging Docker's capabilities, it is essential that the Docker extension is properly installed on your Plesk server. This installation is a fundamental step to unlock all Docker functionalities.

• If you hold administrator privileges for your Plesk instance, you can easily install the extension directly from the Extensions Catalog.
• Should you not be the Plesk administrator, 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 fully prepared to proceed. The "Docker" option will become visible and accessible within the Navigation Pane of your Plesk interface, indicating readiness for use.

Containers

The Run Container catalog provides seamless access to a vast array of images from Docker Hub. You can navigate to this catalog by going to Docker > Containers > Run Container.

To access the container catalog:

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

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

The following repositories are available for searching:

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

Many applications offer multiple versions. To ensure you run a precise version, select the appropriate tag from the available options. The process for running a container is outlined below:

1. Navigate to Docker > Containers > Run Container.
2. Employ the search box to locate desired images within the catalog. If an image is stored locally, it will be clearly indicated with (local) next to its version.
3. To review the image's description and documentation on Docker Hub, click the "more info" icon. Please note that this option is not applicable to local images.
4. Click on the desired image card to proceed.
   • To deploy a specific version, select the preferred image 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 initiate the creation of the container and prompt you to define its settings, such as environment variables, before running it. You have the option to cancel this process at any point by clicking Cancel on the Settings screen. For a detailed understanding of these settings, please refer to the "Container Settings" section further down this page.

5. Once you have finalized and saved the desired settings, click Run. The newly created container will subsequently appear in the list displayed within the Containers tab.

Always review the Console Log to verify that the container is operating without any issues or errors.

Container Settings

Note: When adjusting container settings, there is no requirement to stop the container beforehand. Plesk intelligently recreates the container with the newly applied settings once you save your changes, ensuring minimal downtime.

To modify existing container settings, navigate to the Containers tab and click the settings icon situated next to the specific container you wish to configure.

Limiting Memory

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

Note: Currently, the ability to limit CPU and Disk usage for Docker containers is not available 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

If the Automatic start after system reboot option remains deselected, any websites relying on this container might become unavailable following a system reboot. In such instances, manual intervention will be required to restart the container.

Port Mapping

The Automatic port mapping feature is enabled by default, which assigns a random port on the host system (e.g., 32768) to the container’s internal port.

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

When employing manual mapping, Docker, by default, binds only to the specified port on the host system’s localhost interface (127.0.0.1). This configuration inherently restricts external access, safeguarding the application inside the container from direct internet-based attacks. To enable Docker to bind to the specified port across all network interfaces of the host system, you must deselect the Make the port inaccessible from the Internet option. Be aware that enabling this will make the application within the container accessible from the internet via any of the host system’s IP addresses on the designated port.

Warning: Docker generally presumes that authentication mechanisms are handled by the application itself. However, this is not always the case (for example, while MySQL/MariaDB typically denies anonymous access, Redis might allow it by default). Exposing an application inside a container to the internet without proper authentication and security measures can significantly increase the risk of it being compromised by malicious actors.

Volume Mapping

Docker volumes serve as directories on your server that are mounted to a Docker container. This mechanism provides persistent storage, ensuring that data can be accessed from your host system. Crucially, any data residing within Docker volumes remains intact even when a container is stopped or deleted.

Warning: It is imperative to understand that data stored in Docker volumes will not be included in standard Plesk backups. To mitigate potential data loss, we strongly recommend backing up any critical data stored in a volume using a reliable third-party backup solution.

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

To establish a new volume mapping, you will 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 directory located inside the container.

Should you need to map additional directories, simply click the Add one more button.

Setting Environment Variables

Environment variables play a critical role in configuring applications 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 variables as your setup demands.

Operations with Containers

Plesk provides a suite of essential operations for managing your Docker containers:

• You can effortlessly Stop, Start, or Restart a container. It is important to note that in these scenarios, the container is recreated with its current settings.

  Note: If you have not saved data to mounted volumes (as discussed in the "Volume Mapping" section below), any unsaved data within the container will be lost during recreation.

• Clicking the arrow icon adjacent to a container allows you to inspect its logs and monitor resource consumption in real-time.
• To modify container settings, such as environment variables or volume mappings, click the settings icon next to the desired container. This opens the Settings interface.
• Containers can also be renamed by navigating to Settings > Container name and inputting a new name.

Additional advanced operations are accessible by clicking the "more options" icon next to a container:

• Recreate: This option allows you to rebuild a container using the same or an alternative version of the image.
• Save as Image: Create a new image based on your container, incorporating any custom configurations you've made.
• Download Snapshot: Generate and download a snapshot of your container at its current state.
• Remove: Permanently delete the container.

Recreating a Container

Container recreation is typically required when you intend to update an application to a newer version or revert to an older one. You have the flexibility to rebuild a container using any application version available in the catalog, not just the latest.

Crucially, all custom settings are meticulously preserved during the recreation process. To safeguard the data utilized by the application within a container, it is highly recommended to establish volume mapping prior to recreation. Volume mapping provides persistent access to directories used inside the container, ensuring data continuity.

To initiate the recreation of a container:

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

Using Remote Docker

While Plesk defaults to utilizing Docker installed as a local service, it offers the flexibility to integrate one or more Docker services situated external to your Plesk installation. It is important to remember that only one Docker service can be actively used at any given time. The currently active server can be easily identified within the Environments tab of the Docker settings page in Plesk.

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

Configuring Remote Services

To prepare a remote server running Docker for integration with Plesk, you must configure it precisely as detailed in the official Docker documentation, particularly concerning secure communication (HTTPS).

Managing Remote Services

Plesk facilitates the establishment of a secure connection between a Plesk server equipped with the Docker extension and an external node hosting a Docker service. These instructions are universally applicable to both Plesk for Linux and Plesk for Windows environments.

The following preparatory steps must be executed on the remote host:

1. Create the /etc/docker/daemon.json configuration file for Docker, ensuring it contains 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. Generate the necessary .pem files. You can leverage the following example sequence of commands. Remember to replace the placeholder IP address on line 4 with the actual IP address of your remote node, 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 subsequent commands to modify the existing Docker service, ensuring it automatically starts 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 client connections to the remote Docker host, save the outputs of the following files from the remote machine to your local machine:

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

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

1. Navigate to Docker > Environments.
2. Click Add Server and meticulously enter the configuration details of your remote Docker server.
3. To immediately begin using this specific Docker service within Plesk, ensure the Set active option remains selected.

Upon successful configuration, the Docker link will become available in the Navigation Pane, providing quick access.

To seamlessly switch between different Docker services:

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

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

Creating Images with Custom Settings

Should you wish to generate a new Docker image incorporating modifications you've applied to an existing container, the Save as Image command is your primary tool. This action effectively captures a snapshot of your container's current state, subsequently adding it as a new, distinct image within your image catalog. This functionality is particularly useful for creating personalized images with specific configurations, including tailored environment variables.

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

1. Navigate to Docker > Containers.
2. Click the "more options" icon located next to the container from which you intend to create an image, then click 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 image.
   • Tag (optional): Here, you can define an optional tag, which often represents the image version. If no tag is specified, the default version will be "latest".

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

Managing Local Images

Local images refer to Docker images that are stored directly on your server's local disk. This means they are readily available and do not require re-downloading from the online Image Catalog, offering faster deployment and reduced bandwidth usage.

An image transitions to a local status under several common scenarios:

• When you select any version (tag) of an image and the download process commences. Regardless of whether you subsequently run a container or cancel the operation (from the Settings screen), the image will be saved locally.
• Upon successfully uploading an image to Docker within Plesk, typically via the Upload image function found in the Docker Images tab.
• When you generate a custom image from an existing container, as elaborated in the "Creating Images with Custom Settings" section.
• If you have constructed an image using Docker's command-line interface.

To retrieve a different 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.

When Docker possesses at least one downloaded version within a group of versions associated with a particular image, that image is designated as a Local image in the catalog. Plesk also conveniently displays the total count of local images available for each product, aiding in inventory management.

To effectively view and remove outdated local images:

1. Access the Docker > Images interface.
2. To quickly locate a specific local image, utilize the provided Search bar.
3. To review all local images pertinent to a particular product, click the link situated beneath the product name. This action will reveal all associated local images, their respective tags, and the disk space they currently occupy.
4. Select the individual image(s) you wish to remove 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, enabling applications within them to be accessible. However, when integrating such an application with your website, requiring users to specify a non-standard port in the URL can be inconvenient and less user-friendly.

To overcome this, you can configure Nginx to proxy requests from your domains to the container's exposed port. This allows your domains to utilize a standard port (e.g., 80 or 443), eliminating the need for users to explicitly include the port number in the URL.

Requirements

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

Mapping the Port Inside a Container

Follow these steps to establish port mapping for your container:

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

Once the port is manually mapped, you can proceed to configure Nginx to proxy requests from your domains to this host port, allowing your domains to operate on standard Nginx ports like 80. To achieve this, you need to add a specific proxy rule within your domain's settings.

Adding an Nginx Proxy Rule in Domain Settings

To add a new rule for Nginx within your domain's configuration:

1. Go to Websites & Domains > select your specific domain > Docker Proxy Rules > Add Rule.
2. Specify the following parameters:
   • URL: Define the URL of the website or a specific section of it that will utilize the application running in the Docker container.
   • Container: From the list, select the application that is running as a Docker container.
   • Port: Choose one of the port mappings previously established in the container settings (i.e., a port inside the container mapped to a port on your system). Nginx will then proxy requests to this designated port on the host system.

These proxy rules are intricately integrated into the web server configuration, typically found in the website’s nginx.conf file (located in /var/www/vhosts/system/$domain/conf/). An example configuration snippet looks like this:

#extension docker begin
location ~ ^/.* {
    proxy_pass http://0.0.0.0:9080;
    proxy_set_header Host             $host;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
}
#extension docker end

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

Note: Docker containers that are connected to a website via Proxy Rules typically do not contribute to the subscription’s disk space usage. However, an important exception occurs when a website directory is mounted to a Docker container as a volume; in this particular case, all files residing within that container will indeed be counted towards the website’s total disk space usage.

Deploying Docker Compose YAML Files

Plesk offers versatile methods for deploying Docker Compose YAML files, enabling you to manage multi-container Docker applications efficiently. You can achieve this using the integrated online text editor, by uploading a file from your local storage, or by referencing a Docker Compose file already present within a website’s Home directory.

Standard operations on Docker Compose stacks are fully supported, including up (which encompasses pull and force-recreate functionalities), stop, and down. Furthermore, you retain the ability to modify and update your deployed stacks at any time after their initial creation.

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

To deploy a Docker Compose file, follow these steps:

1. Navigate to Docker > Stacks > Add Stack.
2. Enter a descriptive project name for your stack and then select one of the following deployment methods for your Docker Compose file:
   • Editor: Utilize the built-in editor to define or paste the entire content of your Compose file directly.
   • Upload: Browse and upload a Docker Compose file from your local computer's storage.
   • Webspace: Choose this option to select a Compose file that is already stored within a domain’s Home directory. If selecting this, first specify the domain where the file resides, then use the Compose File browser to locate the exact file.

Plesk also provides the capability to declare and build custom containers as part of your Docker Compose deployment. All 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 specifications, please refer to the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a comprehensive and user-friendly container management software designed to simplify the deployment of individual containers and entire stacks. It provides an intuitive interface for monitoring a container’s status and logs, facilitating user and team creation, and enhancing the overall security of your containerized environments, among many other features.

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

Note: Portainer is currently offered as a beta feature within Plesk.

For additional in-depth information and comprehensive guidance on Portainer, please consult the official Portainer documentation.