Using Docker in Plesk Obsidian

Docker is a powerful platform designed to run applications within isolated environments known as containers. This technology allows users to deploy and operate specific software, such as Redis or MongoDB, or particular software versions, even if they are not natively supported by the host operating system or require specialized compilation processes.

Integrated as a Plesk extension, Docker provides the capability to effortlessly run and manage containers derived from various Docker images. This functionality extends to using Docker both on your local host and across remote servers, offering flexible deployment options.

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

Requirements and Limitations

Warning: The Docker extension directly downloads images 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 setup. Before deploying these downloaded images in Plesk, it is crucial to implement your own security enhancements. For detailed instructions, please refer to the documentation provided by the container or software vendor. For instance, consult 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 installations, Docker can be utilized when installed on a remote machine. Refer to the "Using Remote Docker" section later in this guide for more information.
• It is not possible to use Docker within a Plesk instance that is itself deployed inside a Docker container.
• Utilizing remote Docker services within Plesk requires an additional license. This license can be acquired either separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker functionality is restricted to x64 systems only.
• Docker containers managed within Plesk cannot be directly migrated or backed up. However, it is possible to back up data utilized by these containers (as detailed in the "Volume Mapping" section below) or to download container snapshots.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later is supported. Please note that starting with this update, new containers based on CentOS 7 are provisioned with the firewall enabled by default, reflecting Virtuozzo's enhanced security posture. 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 properly installed on your Plesk server.

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

Once the extension is successfully installed, you will find the "Docker" option conveniently located in the Navigation Pane, indicating that you are ready to proceed with container management.

Containers

You can access a vast collection of images from Docker Hub directly within the Run Container catalog, accessible via Docker > Containers > Run Container.

Accessing the Image Catalog

To access the Docker image catalog:

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

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

The following repositories are available for searching:

• Local repository: This repository contains images that have already been downloaded and are now stored on your server running Docker. For more details, 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 execute a specific version by selecting the appropriate tag from the available options. An example is illustrated below:

Running a Docker Container

To initiate and run a new 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 displayed next to its version.
3. To view the image's detailed description and documentation on Docker Hub (this feature is not applicable to local images), click the more info icon.
4. Click on the desired image card.

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

   Plesk will then proceed to create the container and prompt you to define its essential settings, such as environment variables, before initiating its execution. You have the option to cancel the container deployment at any point by clicking Cancel on the Settings screen. For a comprehensive understanding of these settings, refer to the "Container Settings" section further down this page.

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.

It is recommended to check the Console Log to verify that the container is running without any issues.

Container Settings

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

To modify the settings of an existing container, 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 an unlimited amount of RAM. To enforce a memory limit, simply select the Memory limit checkbox and then input the desired limit value in megabytes into the MB field.

Note: Currently, there are no provisions to limit CPU or disk usage for Docker containers directly within Plesk.

Note: Docker containers are considered administrator-level objects. As such, their resource usage (CPU, RAM, Disk) is not governed by subscription-level cgroup limits.

Automatic Start Configuration

If the Automatic start after system reboot option is not selected, any websites dependent 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 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 a different external port under Manual mapping. If the Manual mapping option does not appear after deselection, it indicates that the container is not configured to expose any ports.

When employing manual mapping, Docker typically binds the specified port exclusively to the host system’s localhost interface (127.0.0.1). This default configuration ensures that the port remains inaccessible from the internet, thereby safeguarding the application within the container from external attacks. To allow Docker to bind the specified port to all network interfaces of the host system, deselect Make the port inaccessible from the Internet. Be aware that by doing so, the application inside the container will become accessible from the public internet and can be reached 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 example, MySQL/MariaDB typically disallows anonymous access by default, whereas Redis might allow it). Making an application within a container accessible from the internet without proper internal authentication mechanisms can expose it to potential attacks from malicious actors.

Volume Mapping for Persistent Storage

Docker volumes represent directories on your server that are mounted directly into a Docker container. This mechanism provides a crucial way to establish persistent storage that can be accessed from your host system. Data stored within Docker volumes is preserved even when a container is stopped or deleted.

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

For more detailed information regarding data in containers, please consult the official Docker documentation.

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

To map additional directories, simply click Add one more.

Setting Environment Variables

Environment variables are utilized by the application running inside a container. You may find it necessary to add new variables or modify existing ones to tailor the application's behavior. Plesk offers the flexibility to add as many environment variables as your application requires.

Operations with Containers

Plesk provides a range of essential operations you can perform on your Docker containers:

• You can Stop, Start, or Restart a container. In each of these scenarios, the container will be recreated according to its current configuration settings.

  Note: If you have not configured data persistence through mounted volumes (as explained in the "Volume Mapping" section), any unsaved data within the container will be lost upon these operations.

• To review logs and monitor resource consumption, click the arrow icon adjacent to the container.
• To modify container settings, such as environment variables or volume mapping, click the settings icon next to the container (labeled Settings).
• A container can also be renamed by navigating to Settings > Container name.

By clicking the more options icon next to a container, you can access additional advanced operations:

• Recreate: Rebuild a container using the same or a different version of its image.
• Save as Image: Create a new Docker image based on the current state of your container, incorporating any custom settings you've applied.
• Download Snapshot: Generate and download a snapshot of the container's current state.
• Remove: Delete the container.

Recreating a Container

Container recreation is typically performed when you intend to update the application to a newer version. However, this feature allows you to rebuild a container using any available application version from the catalog, not exclusively newer ones.

Crucially, any custom settings you have applied to the container are preserved during the recreation process. To safeguard data utilized by the application within the container, it is vital to configure volume mapping prior to initiating a container recreation. Volume mapping ensures you retain access to directories used inside a container. (Please refer to the "Volume Mapping for Persistent Storage" in the container settings section for detailed instructions).

Steps to Recreate a Container:

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

Using Remote Docker

While Plesk defaults to using a locally installed Docker service, you have the flexibility to integrate one or more Docker services hosted externally. It's important to remember 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 Plesk license key add-on. Without this add-on, your operations will be limited to managing only the local Docker service running on the Plesk server.

Configuring Remote Services

To enable a remote server running Docker for use within Plesk, you must configure it as described in the official Docker documentation, focusing on secure communication.

Managing Remote Services

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

Steps to Perform on the Remote Host:

1. Create the /etc/docker/daemon.json configuration file for Docker, populating it 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. You can utilize the example commands provided below. Remember to replace the IP address on line 4 with the actual IP address of your remote node before executing each command:

   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 client.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 automatically starts after the host configuration is complete:

   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 will be required by the client to establish a remote connection:

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

Steps to Configure the Docker Remote Host on the Local Server:

1. Navigate to Docker > Environments.
2. Click Add Server and then provide the necessary settings for the remote server running Docker.
3. To immediately begin using this Docker service within Plesk, ensure that Set active remains selected.

Upon successful configuration, the link to Docker will become visible in the Navigation Pane.

Switching Between Docker Services

To switch the active Docker service within Plesk:

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 designate a Docker node as active directly while editing its settings.

Creating Images with Custom Settings

Should you wish to generate a new Docker image incorporating modifications you've made to an existing container, the Save as Image command is the appropriate tool. This action essentially captures a snapshot of your container's current state, subsequently adding it as a new image to your image catalog. This functionality is invaluable for creating custom images with predefined settings, including specific environment variables.

Steps to Create an Image from a Container:

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

1. Navigate to Docker > Containers.
2. Click the more options icon next to the desired container.
3. Select Save as Image.
4. In the "Save <container name> as Image" side panel that appears, you will need to specify:
   • Image name: A descriptive name for your new image.
   • Tag (optional): You can specify the image version here. If left blank, the version will default to "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 reside directly on your local disk storage. This means there's no need to download them from the online Image Catalog when you want to use them, providing quicker access and reduced bandwidth usage.

An image transitions to a "local" status under several circumstances:

• When you select any specific version (tag) of an image and the download process begins. The image is saved locally whether you proceed to run a container from it or cancel the operation on the "Settings" screen.
• When you actively upload an image to Docker within Plesk using the Upload image option found in the Docker Images tab.
• If you create a custom image directly from an existing container. (For detailed steps, refer to the "Creating Images with Custom Settings" section).
• When an image is built using the command-line interface.

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

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

Viewing and Removing Local Images

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

1. Navigate to Docker > Images.
2. To efficiently locate a specific local image, utilize the Search bar.
3. To view all local images pertaining to a particular product, click the link displayed under the product's name. This action will present all local images' tags along with their occupied disk space.
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 applications running 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 cumbersome. To enhance user experience and simplify access, you can configure Nginx to proxy requests from your domains to the container's designated port. This setup enables your domains to utilize standard web ports (e.g., port 80 or 443), eliminating the need for explicit port specification in the URL.

Requirements for Nginx Proxying:

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

Mapping the Container Port:

To manually map a port inside a container:

1. Navigate to Docker > Containers and click the settings icon next to the container you wish to configure.
2. Disable the Automatic port mapping option.
3. Manually map the container's internal port to a specific port on your host system (e.g., 32768). You have the option to configure this host port to be inaccessible from the public internet for added security.

Once the container's port is manually mapped, you can proceed to configure Nginx to proxy requests. This allows your domains to communicate with the container via a standard Nginx port (such as 80). To achieve this, you will need to add a specific Nginx proxy rule within your domain's settings.

Adding an Nginx Proxy Rule in Domain Settings:

To add a new proxy rule for Nginx:

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

• URL: Define the URL of your website that will utilize the application running in the Docker container. This can be the main website URL or a specific path within it.
• Container: Select the relevant application running as a Docker container from the available list.
• Port: Choose one of the port mappings previously defined in the container settings. Nginx will forward incoming requests to this specific port on your host system.

These proxy rules are implemented directly within the web server configuration, typically found in your website’s nginx.conf file (located at /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's worth noting that these proxy rules are designed to function effectively even 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 occurs if a website directory is mounted directly to a Docker container as a volume; in this specific scenario, all files located within that container will be counted towards the website's allocated 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 selecting a Docker Compose file already stored within a website’s Home directory. Standard operations on Docker Compose stacks are fully supported, 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.

Note: This section specifically addresses Docker Compose YAML files. It is not designed for deploying Dockerfiles or other supplementary application files.

Steps to Deploy a Docker Compose File:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a project name for your stack, and then select one of the following 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: Enables you to upload a Compose file from your local computer storage.
   • Webspace: Provides the option to select a Compose file that is already stored within a domain’s Home directory. If choosing this method, you will need to select the specific domain where the file is located and then browse to the Compose file's path.

Within your Docker Compose file, you have the capability to declare and build custom containers. Any artifacts generated during this build process will be automatically placed inside the respective website’s Home directory.

For a comprehensive understanding of the Compose file format and its specifications, please consult the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a robust container management software designed to simplify the deployment of containers and stacks, facilitate the monitoring of container status and logs, enable user and team creation, and enhance the security of your Docker environments, among other features.

Installing and Accessing Portainer:

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

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

For additional details and in-depth guidance on using Portainer, please refer to the official Portainer documentation.