Using Docker | Plesk Obsidian documentation

Docker is a powerful platform designed to run applications within isolated environments known as containers. This technology allows users to deploy specific software, such as Redis or MongoDB, or particular software versions that might not be natively supported by the operating system or require complex compilation. Integrated as a Plesk extension, Docker provides the capability to efficiently run and manage containers based on various Docker images, supporting operations on both local hosts and remote servers.

This comprehensive guide will walk you through the process of creating, configuring, and managing Docker containers directly within Plesk. Furthermore, you will learn how to effectively control and utilize remote Docker hosts from your Plesk interface.

Requirements and Limitations

Warning: The Docker extension downloads images directly from Docker Hub without any pre-configuration. Some Docker containers or the software within them are designed for trusted environments only and may necessitate additional security configurations. Before deploying these downloaded images within Plesk, it is crucial to independently enhance their security. For specific instructions, always refer to the official documentation provided by the container or software vendor. As an example, please refer to the security section in the Redis documentation.

• 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 a later version.

  For Plesk on Windows, it is possible to utilize Docker installed on a remote machine. For detailed instructions, refer to the "Using Remote Docker" section later in this guide.

• It is not possible to run Docker within a Plesk instance that is itself deployed inside a Docker container.
• To leverage remote Docker services within Plesk, an additional license is required. This license can be acquired separately or as part of the Hosting Pack, Power Pack, or Developer Pack.
• Docker operations are exclusively supported on x64 systems.
• Docker containers managed within Plesk cannot be directly migrated or backed up. However, it is possible to back up data utilized by these containers (refer to the "Volume Mapping" section below) or to download snapshots.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later is supported. It's important to note that with this update, new CentOS 7-based containers are created with the firewall enabled by default, reflecting Virtuozzo's enhanced security measures. Plesk administrators must manually configure the firewall to ensure that all necessary ports for Plesk's operation are open.

Prerequisites

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

• If you possess Plesk administrator privileges, you can install the extension directly from the Extensions Catalog.
• If you are not the Plesk administrator, please reach out to your hosting provider and request them to install the Docker extension on your behalf.

Upon successful installation, the "Docker" option will become visible in the Navigation Pane, indicating that you are ready to proceed with Docker operations.

Containers

Docker images from Docker Hub can be accessed directly within the Run Container catalog in Plesk. Navigate to Docker > Containers > Run Container to explore available images.

Accessing the Container Catalog

• If you have not yet installed any containers, access the catalog by clicking Run Container within Docker > Containers.
• If containers have been previously installed, click the plus icon in Docker > Containers to open the catalog.

To efficiently locate desired images, utilize the search box. You can specify the image name, the repository, or a combination of both.

The following repositories are available for your search:

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

Many applications offer multiple versions. You can deploy a specific version by selecting the appropriate tag from the available options.

Running a Container

1. Navigate to Docker > Containers > Run Container.
2. Utilize the search box to find your desired images within the catalog. If an image is stored locally, (local) will be indicated after its version.
3. To view a detailed description and documentation for an image on Docker Hub, click the "more info" icon . Note that this feature is not applicable to local images.
4. Click on the desired image card.
   • To run a specific version, select your preferred image version from the Image version drop-down menu and then click Next.
   • To deploy the latest available version of the selected application, simply click Next.

   Plesk will then initiate the container creation process and prompt you to configure its settings, such as environment variables. The container will then run automatically. You have the option to cancel the deployment at the Settings screen by clicking Cancel. Comprehensive details regarding container settings are provided in the "Container Settings" section below.

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

Always consult the Console Log to verify that the container is running without any issues.

Container Settings

Note: When modifying container settings, there is no need to stop the running container. Plesk automatically recreates the container with the updated settings upon saving your changes.

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

Limiting Memory Usage

By default, Docker containers operate with unlimited RAM usage. To impose a memory limit, select the Memory limit checkbox and input the desired limit value in megabytes (MB) within the designated field.

Note: Currently, CPU and disk usage cannot be directly limited for Docker containers.

Note: Docker containers are treated as administrator-level objects and are therefore not governed by subscription-level cgroup limits, which include CPU, RAM, and disk usage.

Automatic Start Configuration

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

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 (e.g., 32768).

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

When utilizing manual mapping, Docker typically binds the specified port only to the host system's localhost interface (127.0.0.1). This default configuration ensures the port remains inaccessible from the internet, thereby safeguarding the application within the container from external attacks. To allow Docker to bind to the specified port on 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 specified port.

Warning: While Docker often assumes that authentication is handled by the application itself, this is not always the case (for instance, MySQL/MariaDB typically disallows anonymous access by default, whereas Redis does not). Making an application inside a container accessible from the internet without proper authentication and security measures can expose it to potential attacks from malicious actors.

Volume Mapping

Docker volumes are persistent directories on your server that are mounted to a Docker container. This mechanism provides durable storage that can be accessed from your host system, and the data within Docker volumes is retained even when a container is stopped or deleted.

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

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

To establish a volume mapping, provide the following information:

• In the Host field: Enter the absolute path to the directory on your server that you intend to mount into the container.
• In the Container field: Specify the absolute path to a directory located inside the container.

To map additional directories, click Add one more.

Setting Environment Variables

Environment variables are crucial for configuring the application running inside a container. You may need to add new variables or modify existing ones to suit your application's requirements. Plesk allows you to add an unlimited number of environment variables as needed.

Operations with Containers

Plesk provides a range of operations to effectively manage your Docker containers:

• Stop, Start, or Restart: You can easily stop, start, or restart a container using the respective Stop, Start, or Restart actions. It's important to note that performing these actions will cause the container to be recreated with its current settings.

  Note: If data has not been saved to mounted volumes (as discussed in the "Volume Mapping" section), this data will be lost upon container recreation.

• View Logs and Resources: Click the arrow icon next to a container to access its logs and monitor resource consumption.
• Edit Settings: To modify container settings, such as environment variables or volume mapping, click the settings icon next to the desired container.
• Rename Container: You can rename a container by navigating to its Settings and then modifying the Container name field.

Additionally, clicking the "more options" icon next to a container reveals further actions:

• Recreate: Rebuild a container using either the same image version or an alternative one.
• Save as Image: Create a new image based on your container with its custom settings.
• Download Snapshot: Generate and download a snapshot of the container's current state.
• Remove: Permanently delete the container.

Recreating a Container

Container recreation is typically performed when you need to update the application within to a newer version. This process allows you to rebuild a container using any available application version from the catalog, not just a newer iteration.

Crucially, custom settings are preserved during the recreation process. To ensure the preservation of data used by the application inside a container, it is essential to define volume mapping prior to initiating recreation. Volume mapping facilitates access to the directories utilized within a container. (For detailed information, refer to the Volume Mapping section within container settings).

To recreate a container, follow these steps:

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

Using Remote Docker

While Plesk defaults to using Docker installed as a local service, it also offers the flexibility to integrate with one or more external Docker services. It's important to note that only one Docker service can be active at any given time. The currently active server can be identified within the Environments tab of the Docker settings page in Plesk.

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

Configuring Remote Services

To enable a remote server running Docker to function as a remote host within Plesk, you must configure it as detailed in the official Docker documentation regarding secure communication.

Managing Remote Services

The Plesk Docker extension allows you to establish a secure connection between your Plesk server and a remote node hosting a Docker service. The following configuration steps are applicable to both Plesk for Linux and Plesk for Windows environments.

Steps to Perform on the Remote Host:

1. Create Docker Configuration File: Create the /etc/docker/daemon.json configuration file 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 .pem Files: Generate the necessary .pem files for secure communication. You can adapt the following example. Remember to replace the IP address on line 4 with the actual IP address of your remote node before executing 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: Execute the following commands to modify the current Docker service, ensuring it starts correctly after the 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 Client Files: For the client to connect remotely, save the outputs of the following files onto your local machine:

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

Configuring the Docker Remote Host on the Local Server:

1. Navigate to Docker > Environments.
2. Click Add Server and proceed to specify the connection settings for your remote Docker server.
3. To immediately activate this Docker service within Plesk, ensure that the Set active option remains selected.

Upon successful configuration, a link to Docker will appear in the Navigation Pane, providing access to the remote service.

Switching Between Docker Services

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

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

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

Creating Images with Custom Settings

To generate a new Docker image that incorporates the modifications you've made to a container, utilize the Save as Image command. This function captures a snapshot of your current container, which is then added as a new image entry in your image catalog. This capability is particularly useful for creating specialized images with custom configurations, including unique environment variables.

Steps to Create an Image from a Container:

Navigate to Docker > Containers, then click the "more options" icon alongside the container you wish to use. From the dropdown, select Save as Image. In the "Save <container name> as Image" side panel, you will need to specify the following details:

• Image name: Provide a descriptive name for your new image.
• Optional Tag: You can define a specific version for the image here. If no tag is provided, the default version will be "latest".

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

Managing Local Images

Local images are Docker images that are persistently stored on your local disk, eliminating the need to download them from the online Image Catalog for subsequent use.

An image transitions to a local state under several circumstances:

• When you select any version (tag) of an image and the download process begins. The image is saved locally whether you proceed to run a container or cancel the operation from the Settings screen.
• If you explicitly upload an image to Docker within Plesk using the Upload image function in the Docker Images tab.
• When you create a custom image directly from an existing container. (Refer to the "Creating Images with Custom Settings" section for more details.)
• Upon building an image using the command-line interface.

To download an alternative version of an image from the online catalog, click the Pull icon . From the dropdown menu, select the desired version and then click Pull.

If Docker has at least one downloaded version associated with an image, that image will be designated as a Local image in the catalog. Plesk conveniently displays the total count of local images available for a particular product.

Viewing and Removing Local Images:

To manage your local images, including removing outdated ones, follow these steps:

1. Navigate to Docker > Images.
2. Utilize the Search bar to quickly locate a specific local image.
3. To inspect all local images belonging to a particular product, click the link located beneath the product name. This action will display all local images’ tags along with the disk space they 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

Certain Docker containers are configured to expose specific ports, allowing applications within them to be accessed via these ports. When integrating a Dockerized application into your website, directly specifying a non-standard port in the URL can be cumbersome. To enhance user experience and simplify access, you can configure Nginx to proxy requests from your domains to the container's port, enabling domains to use a standard web port (such as 80) without requiring explicit port specification in the URL.

Requirements:

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

Mapping the Port Inside a Container:

1. Navigate to Docker > Containers and click the settings icon adjacent to the container you wish to configure.
2. Disable the Automatic port mapping option.
3. Manually map the internal container port to a specific port on your system (for example, 32768). You have the option to make this host port inaccessible from the Internet for added security.

Once the port is mapped, you can configure Nginx to proxy requests from your domains to this host port, allowing domains to operate on a standard Nginx port (e.g., 80). To achieve this, you need to add a proxy rule within the domain settings.

Adding an Nginx Proxy Rule in Domain Settings:

Go to Websites & Domains > select your specific domain > Docker Proxy Rules > Add Rule, and then provide the following details:

• URL: Specify the URL of the website that will utilize the application running in the Docker container. This can be the main website URL or a specific subdirectory.
• Container: Select the relevant application running as a Docker container from the dropdown.
• Port: Choose one of the port mappings previously configured in the container settings (i.e., the internal container port mapped to a port on your host system). Nginx will then proxy requests to this specified host system port.

These proxy rules are implemented directly within the web server configuration, typically found in the website’s nginx.conf file (located at /var/www/vhosts/system/$domain/conf/), and will appear similar to this example:

#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 designed to function effectively on servers operating 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. An important exception is when a website directory is mounted to a Docker container as a volume; in such a scenario, all files located within that container will be accounted for in the website's disk space usage.

Deploying Docker Compose YAML Files

Plesk facilitates the deployment of Docker Compose YAML files through various convenient methods: using an online text editor, uploading a file from your local storage, or by referencing a Docker Compose file already present within a website’s Home directory. Common stack operations, including up (which encompasses pull and force-recreate), stop, and down, are fully supported. Furthermore, stacks can be modified and updated even after their initial creation.

Note: This section is specifically for Docker Compose YAML files. It is not intended for deploying Dockerfiles or any other supplementary files required by an application.

Steps to Deploy a Docker Compose File:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a descriptive project name and then select one of the available deployment methods for your Docker Compose file:
   • Editor: Allows you to directly define or paste the content of your Compose file into a text editor.
   • Upload: Provides an option to upload a Compose file directly from your local storage.
   • Webspace: Enables you to select a Compose file that is already stored within a domain’s Home directory. For this method, you will need to choose the relevant domain where the file is located and then browse to the exact Compose file location.

Through this process, you can declare and build custom containers. Any artifacts generated during the build process will be systematically placed within the associated website’s Home directory.

For comprehensive details on the Docker Compose file format and its capabilities, please consult the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a highly effective container management software designed to simplify various aspects of Docker operations. It streamlines the deployment of containers and stacks, offers intuitive views of container status and logs, facilitates user and team creation, and assists in securing your containerized environments, among many other features.

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

Note: Portainer is currently offered as a beta feature.

For comprehensive documentation and further details on Portainer, please refer to the official Portainer documentation.