Using Docker with Plesk Obsidian

Docker is a powerful platform that allows you to run applications within isolated containers. This capability is incredibly useful for deploying specific software, such as Redis or MongoDB, or for utilizing particular software versions that might not be natively supported by your operating system or that require custom compilation. As a Plesk extension, Docker provides the ability to efficiently run and manage containers based on various Docker images, supporting operations on both local hosts and remote servers.

This guide will walk you through the process of creating, configuring, and managing Docker containers directly within Plesk. Additionally, you will learn how to effectively control remote Docker hosts from your Plesk interface, streamlining your application deployment and management workflows.

Requirements and Limitations

Warning: The Docker extension downloads images directly from Docker Hub without any prior preconfiguration. It is crucial to understand that some Docker containers or the software they contain are intended for trusted environments only and may necessitate additional security configurations. Before launching any downloaded images in Plesk, you must enhance their security manually. For detailed instructions, 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 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 (version 7.0.1-686) or a later update.
• For Plesk on Windows, you have the option to use Docker installed on a remote machine. Refer to the Using Remote Docker section later in this guide for more details.
• It is not possible to run Docker within a Plesk instance that is itself deployed as a Docker container.
• To leverage remote Docker services in Plesk, an additional license is required. This license can be acquired either 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.
• Currently, Docker containers within Plesk cannot be migrated or backed up directly. However, you can back up the data utilized by these containers (as explained in the Volume Mapping section below) or download container snapshots for data preservation.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later is supported. Please note that with this update, newly created containers based on CentOS 7 will have the firewall enabled by default. This is a security measure implemented by Virtuozzo. 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 properly installed on your Plesk server:

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

Once the extension is successfully installed, you will find the Docker option readily available in the Navigation Pane, indicating that you are now prepared to proceed with Docker integration.

Containers

You can effortlessly access a wide array of images from Docker Hub through the Run Container catalog, located by navigating to Docker > Containers > Run Container.

To access this catalog:

• If you haven't installed any containers previously, go to Docker > Containers and click Run Container.
• If you have existing containers, navigate to Docker > Containers and click the plus icon to add a new one.

To locate available images, simply use the search box provided. You can specify the image name, the repository, or a combination of both to narrow down your search results.

The following repositories are available for your search:

• Local repository: This contains images that have already been downloaded and are stored directly on your server, making them immediately accessible. For more details, refer to the Managing Local Images section later in this guide.
• Docker Hub: The official cloud-based repository for Docker images.

It's important to note that multiple versions may be available for each application. You have the flexibility to run a specific version by selecting the appropriate tag from the available options.

To run a container:

1. Navigate to Docker > Containers > Run Container.
2. Utilize the search box to find desired images within the catalog. If an image is stored locally, (local) will be displayed next to its version.
3. To view a detailed description and documentation for an image on Docker Hub, click the more info icon. This option is not applicable to local images.
4. Click on the image card you wish to use.

   • To run a specific version, select your preferred image version from the Image version drop-down menu and then click Next.
   • To run the latest available version of the selected application, simply click Next.

   Plesk will then proceed to create a container and prompt you to specify its initial settings, such as environment variables, before running it. You can choose to cancel the container launch by clicking Cancel on the Settings screen. For a comprehensive understanding of these settings, please refer to the Container Settings section further down this page.

5. After you have finalized and adjusted the settings to your requirements, click Run. The newly launched container will then appear in the list within the Containers tab.

Always review the Console Log to ascertain whether the container is operating without 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 access and edit a container's settings, go to the Containers tab and click the settings icon located next to the container you wish to configure.

Limiting Memory

By default, Docker containers operate with an unlimited amount of RAM. To establish a memory ceiling, select the Memory limit checkbox and input the desired limit value in megabytes within the MB field.

Note: Currently, CPU and Disk usage cannot be restricted for Docker containers directly through Plesk. It is also important to remember that Docker containers are administrator-level objects and are therefore not subject to subscription-level cgroup limits (CPU, RAM, Disk usage).

Automatic Start

If the Automatic start after system reboot option is not selected, any websites that rely on this container may become unavailable after a system reboot. In such cases, you would be required to manually start the container to restore service.

Port Mapping

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

To manually specify the port on the host system, deselect Automatic port mapping and enter a different external port in the Manual mapping field. If the Manual mapping option does not appear after deselection, it signifies that the container does not expose any ports.

When employing manual mapping, Docker typically binds only to the specified port on the host system's localhost interface (127.0.0.1). This configuration prevents direct internet access to the port, thereby safeguarding the application within the container from external attacks. To allow Docker to bind to the specified port across all network interfaces of the host system, deselect Make the port inaccessible from the Internet. Be aware that enabling this option 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 assumes that authentication is handled by the application itself. However, this is not always the case (for example, MySQL/MariaDB typically requires authentication, while Redis might not by default). Exposing an application inside a container to the internet without proper authentication can significantly increase its vulnerability to malicious actors.

Volume Mapping

Docker volumes are essentially directories on your server that are mounted to a Docker container. This mechanism provides persistent storage that can be accessed and managed directly from your host system. Data stored in Docker volumes remains intact even when you stop or delete a container, ensuring data persistence.

Warning: It is critical to understand that data stored in Docker volumes will not be included in standard Plesk backups. To prevent any potential data loss, you must back up any essential data residing in a volume using a third-party backup tool.

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

To establish a volume mapping, you need to specify the following:

• In the Host field: Provide the absolute path to the directory on your server that you intend to mount within the container.
• In the Container field: Specify the absolute path to a directory inside the Docker container where the host directory will be mounted.

To map additional directories, simply click Add one more.

Setting Environment Variables

Environment variables are crucial parameters utilized by the application running inside a container. You may frequently need to add new variables or modify existing ones to tailor the application's behavior. Plesk offers the flexibility to add as many variables as your application requires, allowing for extensive customization.

Operations with Containers

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

• Stop, Start, or Restart a container. In each of these scenarios, the container will be recreated using its current settings.

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

• Click the arrow icon next to the container to view detailed logs and monitor its resource consumption.
• Click the settings icon next to the container to modify its configuration, including environment variables or volume mapping.
• Rename a container by going to its Settings and updating the Container name field.

Click the more options icon next to a container to access additional functionalities, including:

• Recreate a container, either using the same image version or selecting a different one from the catalog.
• Save as Image to create a new image based on your container's current state and custom settings.
• Download Snapshot to take a snapshot of the container's current state.
• Remove a container when it is no longer needed.

Recreating a Container

Recreating a container is a common procedure, particularly when you need to update an application to a newer version. This functionality allows you to rebuild a container using any available application version from the catalog, not just newer ones.

Importantly, all custom settings are preserved during the recreation process. To ensure data persistence for applications within a container, it is highly recommended to configure volume mapping before initiating a recreation. Volume mapping provides access to directories used inside a container, preventing data loss (refer to Volume Mapping in container settings for detailed information).

To recreate a container:

1. Go to Docker and click the more options icon next to the container you wish to recreate.
2. Click Recreate in the container settings panel. You will then be prompted to specify the desired image version and whether to utilize default environment variables.

Using Remote Docker

By default, Plesk integrates with Docker installed as a local service on the same server. However, for enhanced flexibility and resource management, you have the option to utilize one or more Docker services installed on external, remote machines. While you can configure multiple remote services, only one can be active at a 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 Docker management capabilities will be limited to the local Docker service running on your Plesk server.

Configuring Remote Services

To successfully integrate a remote server running Docker with Plesk, you must configure it as described in the official Docker documentation on engine security with HTTPS.

Managing Remote Services

Establishing a secure connection between your Plesk server (with the Docker extension installed) and a remote node hosting the Docker service is straightforward. The following steps are applicable for both Plesk for Linux and Plesk for Windows environments.

These steps must be performed on the remote host:

1. Create the /etc/docker/daemon.json configuration file for Docker with the following content:

   {
     "hosts": ["tcp://0.0.0.0:2376", "unix:///var/run/docker.sock"],
     "tls": true,
     "tlsverify": true,
     "tlscacert": "/root/ca.pem",
     "tlscert": "/root/server-cert.pem",
     "tlskey": "/root/server-key.pem"
   }

2. Prepare the necessary .pem files for TLS authentication. You can use the following example commands. Remember to replace the IP address on line 4 with the actual IP address of your remote node and 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:

   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 onto your local machine. These files are essential for the client to establish a remote connection:

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

On the local Plesk server, configure the Docker remote host:

1. Go to Docker > Environments.
2. Click Add Server and input the necessary settings for the remote server hosting Docker.
3. To immediately begin using this Docker service within Plesk, ensure that Set active is selected.

Once configured, the link to the Docker management interface will appear in the Navigation Pane.

To switch between different Docker services:

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

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

Creating Images with Custom Settings

Should you wish to generate a new Docker image based on modifications you've applied to an existing container, utilize the Save as Image command. This action captures a snapshot of your container's current state, which then appears as a brand-new image within your image catalog. This feature is particularly useful for creating personalized images with custom configurations, such as specific environment variables.

To create an image from one of your containers:

Go to Docker > Containers, click the more options icon next to the container you want to snapshot, and then click Save as Image. In the Save <container name> as Image side panel, you will need to specify:

• The Image name.
• An optional Tag, which can be used to denote the image version. By default, the version will be set to “latest”.

The newly created image will be listed in the Images tab and prominently 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 from the online Image Catalog each time they are used.

An image becomes local under several circumstances:

• When you select and begin downloading any version (tag) of an image. Even if you later run a container or cancel the process on the Settings screen, the image remains saved locally.
• If you upload an image to Docker directly within Plesk using the Upload image option in the Docker Images tab.
• When you create a custom image from an existing container (as described in the Creating Images with Custom Settings section).
• If you have built an image using the command line interface outside of Plesk.

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

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

To view and manage your local images, including removing outdated ones:

1. Go to Docker > Images.
2. To locate a specific local image, use the Search bar.
3. To display all local images associated with a particular product, click the link beneath the product name. This will show all local images' tags and the disk space they occupy.
4. Select the specific image(s) you wish to remove and click Remove.

Setting up Nginx to Proxy Requests from Domains to a Container

Certain Docker containers are designed to expose ports, enabling applications running within them to be accessible via those specific ports. When integrating such an application from a Docker container into your website, it can be inconvenient for users to constantly specify a non-standard port in the URL. To overcome this, you can configure Nginx to proxy requests from your domains to that specific port, allowing domains to use a standard port (like 80 or 443) without explicitly requiring the port in the URL.

Requirements

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

To manually map the port inside a container:

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

Once the port is manually mapped, you can configure Nginx to proxy requests from your domains to that specific host port. This allows domains to utilize a standard Nginx port (such as 80) seamlessly. To enable this, you need to add a proxy rule within the domain settings.

To add a rule for Nginx in the domain settings:

Go to Websites & Domains > select your domain > Docker Proxy Rules > Add Rule and 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: Select the specific Docker container application that you want to proxy requests to.
• Port: Choose one of the port mappings that were previously configured in the container's settings (i.e., the internal container port mapped to a port on your system). Nginx will then proxy incoming requests to this designated port on the host system.

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

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

It's worth noting that proxy rules are generally designed to function effectively even on servers situated behind Network Address Translation (NAT).

Note: Docker containers connected to a website via Proxy Rules typically do not contribute to the subscription’s reported disk space usage. An exception to this rule occurs when a website directory is directly mounted to a Docker container as a volume; in such instances, all files residing within that container will be included in the website's disk space calculation.

Deploying Docker Compose YAML Files

Plesk provides a streamlined way to deploy applications using Docker Compose YAML files. You have multiple options for deployment: leveraging the online text editor to define your Compose file, uploading a file directly from your local storage, or utilizing a Docker Compose file already stored within a website’s Home directory. Plesk supports essential operations on Docker stacks, including up (which encompasses pull and force-recreate), stop, and down. Furthermore, you retain the ability to modify and update your deployed stacks even after their initial creation.

Note: This section is specifically for deploying Docker Compose YAML files. You cannot deploy Dockerfiles or any other application-specific files using this interface.

To deploy a Docker Compose file:

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

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

You can also 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 website’s Home directory.

For detailed information on the Docker Compose file format and its capabilities, please refer to the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a comprehensive container management software designed to simplify the deployment of containers and stacks. It offers an intuitive interface for viewing container statuses and logs, creating users and teams, securing your environments, and much more, significantly streamlining Docker operations.

To install Portainer, navigate to Docker > Install Portainer. Once the installation is complete, you can begin managing your Portainer containers within Docker by going to Docker > Go to Portainer.

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

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