Using Docker | Plesk Obsidian Documentation

Docker is a powerful platform designed for running applications within isolated environments known as containers. This technology allows you to utilize specific software, such as Redis or MongoDB, or particular versions of software that might not be natively supported by your operating system or require complex compilation processes.

Integrated into Plesk as an extension, Docker provides the capability to effortlessly run and manage containers based on various Docker images. It offers the flexibility to deploy Docker both on your local host and on remote servers, streamlining your application deployment workflow.

This comprehensive guide will walk you through the essential steps of creating, configuring, and managing Docker containers directly within Plesk. Furthermore, you will gain insights into effectively controlling and interacting with remote Docker hosts from your Plesk interface, ensuring a robust and scalable infrastructure.

Requirements and Limitations

Warning: The Docker extension downloads images directly from Docker Hub without any pre-configuration. It is crucial to understand that some Docker containers or the software within them are intended for trusted environments only and may necessitate additional security configurations. Before deploying these downloaded images in Plesk, it is your responsibility to enhance their security. Always refer to the specific documentation provided by the container or software vendor for detailed security instructions. For instance, you can consult the security section in the Redis documentation for 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 any later updates.
• For Plesk installations on Windows, you can effectively utilize Docker by deploying it on a remote machine. For more details on this setup, please refer to the section on Using Remote Docker later in this guide.
• It is important to note that you cannot 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 either separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker is designed to run exclusively on x64 systems, ensuring optimal performance and compatibility.
• Please be aware that Docker containers within Plesk cannot be migrated or backed up directly. However, you have the option to back up the data utilized by these containers (as explained in 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 fully supported. Starting with this update, newly created containers based on CentOS 7 will have the firewall enabled by default, a security enhancement introduced 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 leveraging Docker's capabilities, the Docker extension must be successfully installed on your Plesk server. If you are the Plesk administrator, you can easily install the extension directly from the Extensions Catalog. Otherwise, please reach out to your hosting provider and request them to install the Docker extension on your behalf.

Once the extension is installed, you will find the "Docker" option conveniently located in the Navigation Pane, indicating that you are ready to explore and utilize Docker within your Plesk environment.

Containers

Plesk provides seamless access to a vast array of images from Docker Hub through the Run Container catalog, accessible via Docker > Containers > Run Container.

Accessing the Container Catalog

To access the catalog and begin your journey with Docker containers:

• If you have not previously installed any containers, navigate to Docker > Containers, and then click the Run Container button.
• If you have existing containers installed, go to Docker > Containers, and click the plus icon to initiate the process of running a new container.

You can efficiently locate available images by utilizing the search box. Simply specify the image name, the repository, or both to refine your search results.

The following repositories are available for your search:

• Local repository: This repository contains images that have already been downloaded and are now stored locally on your server where Docker is installed. For more comprehensive information, refer to the section on Managing Local Images further in this document.
• Docker Hub: The official Docker image registry, offering a vast collection of public and private images.

For each application, multiple versions might be available. You have the flexibility to run a specific version by selecting the appropriate tag from the options presented.

Running a Container

Follow these steps to successfully run a new Docker container:

1. Navigate to Docker > Containers > Run Container.
2. Utilize the search box to discover suitable images within the catalog. If an image is stored locally on your server, (local) will be displayed after its version, indicating its origin.
3. To review the image's description and documentation on Docker Hub, click the more info icon. Please note that this option is not available for local images.
4. Click on the desired image card to proceed.
   • To run a specific version of the application, select your preferred image version from the Image version drop-down menu and then click Next.
   • Alternatively, to deploy the latest available version of the selected application, simply click Next.

   Plesk will then initiate the creation of the container and prompt you to define its essential settings, such as environment variables. After these settings are configured, the container will be launched. You can always cancel the running process by clicking Cancel on the Settings screen. For a detailed explanation of available settings, refer to the Container Settings section on this page.

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

It is always recommended to review the Console Log to ensure the container is running without any issues and to troubleshoot any potential problems.

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

Limiting Memory

By default, Docker containers operate with unlimited access to system RAM. To impose a memory constraint, select the Memory limit checkbox and input the desired limit in megabytes into the designated MB field.

Note: At present, it is not possible to limit CPU and Disk usage for Docker containers directly within Plesk.

Note: Docker containers are considered administrator-level objects and are not subject to subscription-level cgroup limits (which typically govern CPU, RAM, and Disk usage).

Automatic Start

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

Port Mapping

By default, Automatic port mapping is enabled, which maps the container’s internal port to a randomly assigned port on the host system (for example, port 32768).

To change the port on the host system, deselect Automatic port mapping and then specify a different external port in the Manual mapping field. If Manual mapping does not appear after deselecting the automatic option, it indicates 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 the port from being accessible 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, reachable on the specified port via any of the host system’s IP addresses.

Warning: Docker generally assumes that authentication is handled by the application itself. However, this is not always the case (for instance, MySQL/MariaDB typically requires authentication by default, whereas Redis might not). Making an application within a container accessible from the Internet without proper authentication can expose it to potential attacks from malicious actors.

Volume Mapping

Docker volumes are essentially directories on your server that are mounted to a Docker container. This mechanism provides persistent storage, meaning that the data stored in Docker volumes is retained even if you stop or delete a container. It also allows data to be easily accessed and managed directly from your host system.

Warning: It is crucial to understand that data stored within Docker volumes will not be included in standard Plesk backups. To prevent any data loss, it is highly recommended to back up any critical information stored in a volume using a reliable third-party backup tool.

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 within the container.
• In the Container field: Specify the absolute path to a directory located inside the container where the host directory will be mounted.

To map additional directories, simply click the Add one more button.

Setting Environment Variables

Environment variables are crucial for 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 allows you to define as many environment variables as your application requires, offering extensive customization options.

Operations with Containers

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

• You can easily stop (Stop), start (Start), or restart (Restart) a container. In each of these cases, the container will be recreated based on its current configuration settings.

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

• Click the arrow icon adjacent to a container to access its logs and monitor its resource consumption, providing valuable insights into its performance and status.
• To adjust container settings, such as environment variables or volume mapping, click the settings icon next to the container (Settings).
• Rename a container for better organization by navigating to Settings > Container name.

For additional actions, click the more options icon next to the container to reveal a menu with the following capabilities:

• Recreate: Rebuild a container using the same image version or opt for a different one.
• Save as Image: Create a new image based on your container's current state and custom settings.
• Download Snapshot: Generate and download a snapshot of your container for backup or migration purposes.
• Remove: Permanently delete a container from your system.

Recreating a Container

Recreating a container is a common procedure, particularly when you need to update an application to a newer version or revert to an older one. This process allows you to rebuild the container using any available application version from the catalog.

Importantly, any custom settings you have applied to the container are preserved during recreation. To ensure the persistence of data used by the application inside the container, it is highly recommended to define volume mapping before initiating a recreation. Volume mapping provides a mechanism to maintain access to directories utilized within a container, preventing data loss (refer to Volume Mapping in the container settings for more details).

To recreate a container:

1. Navigate to Docker and click the more options icon next to the container you intend to recreate.
2. Select Recreate from the menu. You will then be prompted to specify the desired image version and whether to utilize default environment variables for the new container instance.

Using Remote Docker

While Plesk defaults to using Docker installed as a local service, it provides the flexibility to connect to and manage one or more Docker services hosted on external, remote machines. It's important to note that you can only designate and actively use one Docker service at any given time. The currently active server is clearly indicated 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 capabilities will be limited to managing only the local Docker service running directly on the Plesk server.

Configuring Remote Services

To effectively utilize a remote server running Docker with Plesk, you must configure it as described in the official Docker documentation, specifically focusing on setting up secure communication for remote access.

Managing Remote Services

Plesk facilitates the establishment of a secure connection between your Plesk server (with the Docker extension installed) and a remote node hosting a Docker service.

The following steps are applicable for both Plesk for Linux and Plesk for Windows environments:

These initial steps must be performed on the remote host:

1. Create the configuration file for Docker, located at /etc/docker/daemon.json, 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 example commands below. 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 and system reboots:

   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. Finally, save the outputs of the following files on your local machine. These files contain the necessary credentials for the client to establish a secure remote connection:

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

On the local Plesk server, proceed with configuring the Docker remote host:

1. Navigate to Docker > Environments.
2. Click Add Server and carefully input the settings corresponding to your remote Docker server.
3. To immediately begin using this Docker service within Plesk, ensure that the Set active option remains selected.

Upon successful configuration, the link to the active Docker environment will conveniently appear in the Navigation Pane.

Switching Between Docker Services

To effortlessly switch between different Docker services:

1. Go to Docker > Environments.
2. From the displayed list of servers, select the desired Docker node that you wish to utilize and click Set Active.

Alternatively, you can also set a Docker node as active while you are in the process of editing its settings, offering greater flexibility.

Creating Images with Custom Settings

If you have made specific modifications or configurations to a running container and wish to save these changes as a reusable blueprint, you can use the Save as Image command. This action effectively takes a snapshot of your container's current state, which then appears as a new, custom image in your image catalog. This feature is particularly useful for creating images with pre-defined custom settings, such as tailored environment variables.

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

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

• Image name: A descriptive name for your new custom image.
• An optional Tag: Here, you can specify the version of the image. By default, if no tag is provided, the version will be designated as "latest."

The newly created image will then be listed in the Images tab and will be 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 an online Image Catalog each time they are needed. This significantly speeds up container deployment and reduces reliance on external network connectivity.

An image becomes a local image under several circumstances:

• When you select any version (tag) of an image and the download process begins. Even if you subsequently run a container or cancel the running process (from the Settings screen), the image will remain saved locally.
• If you manually upload an image to Docker within Plesk using the Upload image option in the Docker Images tab.
• When you create a custom image directly from an existing container (as detailed in the Creating Images with Custom Settings section).
• If you have built an image using the command-line interface (CLI).

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

If at least one downloaded version from a group of versions belonging to a specific image is present on your local system, this image will be labeled as a Local image in the catalog. Plesk will also display the number of local images available for a particular product.

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

1. Navigate to Docker > Images.
2. To quickly locate a specific local image, use the provided Search bar.
3. To view all local images associated with a particular product, click the link displayed under the product name. This action will present all local images' tags and the disk space they currently occupy.
4. Select the specific image(s) you wish to remove and then click Remove.

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 these ports. However, directly specifying non-standard ports in a website's URL can be inconvenient for users.

To enhance user experience and simplify access, you can configure Nginx to proxy requests from your domains to these container-exposed ports. This setup enables your domains to utilize standard web ports (such as 80 or 443) without the need for users to explicitly specify the container's port in the URL.

Requirements

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

Mapping the Port Inside a Container

To manually map the port inside a container, follow these steps:

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

Adding an Nginx Proxy Rule in Domain Settings

Once the container port is mapped, you can set up Nginx to proxy requests. To add a rule for Nginx in your domain settings:

Navigate to Websites & Domains > your domain > Docker Proxy Rules > Add Rule, and then specify the following details:

• URL: Define the URL of the website or a specific part of it that will utilize an application running within a Docker container.
• Container: Select the Docker container that hosts the application you wish to proxy to.
• Port: Choose one of the port mappings that you previously defined in the container settings (specifically, the port inside the container mapped to a port on your system). Nginx will then proxy incoming requests to this designated port on the system.

These proxy rules are implemented within the web server configuration, typically found in the website’s nginx.conf file (located 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 is worth noting that proxy rules generally function effectively on servers deployed behind a Network Address Translator (NAT).

Note: Docker containers connected to a website via Proxy Rules typically do not contribute to the subscription’s disk space usage. An important exception to this is when a website directory is mounted directly to a Docker container as a volume; in such cases, all files located within that container will be accounted for in the website's total disk space usage.

Deploying Docker Compose YAML Files

Plesk simplifies the deployment of Docker Compose YAML files, providing multiple convenient methods: you can utilize the online text editor to define your Compose file, upload a file directly from your local storage, or select an existing Docker Compose file already stored within a website’s Home directory. Plesk supports typical 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 after their initial creation, offering ongoing flexibility.

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

To deploy a Docker Compose file:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a unique project name and choose one of the available methods for deploying your Docker Compose file:
   • Editor: This option allows you to directly define or paste the content of your Compose file into a web-based text editor.
   • Upload: Use this method to upload a Docker Compose file from your local computer storage.
   • Webspace: Select this option if your Compose file is already stored within a domain’s Home directory. When choosing Webspace, you will need to specify the domain where the file is located and then browse to the precise location of the Compose file.

You also have the capability to declare and build custom containers as part of your Docker Compose setup. Any artifacts generated during the build process will be automatically placed within the designated website’s Home directory.

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

Deploying Portainer Containers in Docker

Portainer is an intuitive and powerful container management software that significantly simplifies the deployment and oversight of containers and stacks. It offers a user-friendly interface to view container status and logs, manage users and teams, secure your Docker environments, and much more, centralizing your container operations.

To install Portainer within your Plesk Docker environment, navigate to Docker > Install Portainer. Once the installation is complete, you can effortlessly manage your Portainer containers by going to Docker > Go to Portainer, which will direct you to the Portainer interface.

Note: Portainer integration is currently designated as a beta feature.

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