Using Docker in Plesk Obsidian

Docker serves as a robust platform for deploying and managing applications within isolated containers. This functionality enables users to deploy specific software, such as Redis or MongoDB, or to utilize particular software versions that might not be natively supported by their operating system or may require specialized compilation.

The Docker extension for Plesk provides a comprehensive interface for running and managing containers based on Docker images, allowing for both local and remote Docker host operations.

This topic will guide you through the process of creating, configuring, and managing Docker containers in Plesk. Additionally, you will learn how to effectively control remote Docker hosts directly from your Plesk environment.

Requirements and Limitations

Warning: The Docker extension downloads images directly from Docker Hub without any prior preconfiguration. Some Docker containers or the software within them are intended for trusted environments only and may necessitate additional security configurations. Before launching these downloaded images within Plesk, it is crucial to enhance their security independently. For specific 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 detailed guidance.

• Docker is officially supported in Plesk for the following operating systems: CentOS 7, Red Hat Enterprise Linux 7, Debian 10, Debian 11, Debian 12, Ubuntu 18.04, Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, AlmaLinux 8.x, AlmaLinux 9.x, Rocky Linux 8.x, and Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later versions. For Plesk on Windows, it is possible to use Docker installed on a remote machine; further details are available in the section on Using Remote Docker.
• It is not possible to utilize Docker within a Plesk instance that is itself deployed inside 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 exclusively operates on x64 systems.
• Docker containers managed within Plesk cannot be directly migrated or backed up using Plesk's native backup features. However, you can back up the data utilized by these containers through Volume Mapping, or by downloading container snapshots.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or newer is supported. It's important to note that, starting with this update, new containers based on CentOS 7 are provisioned with the firewall enabled by default. This change reflects Virtuozzo's enhanced security protocols. Consequently, Plesk administrators must manually configure the firewall to ensure that all necessary ports for Plesk's operation are open.

Prerequisites

Before you can begin leveraging Docker's capabilities, 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.
• Otherwise, please contact 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 conveniently located in the Navigation Pane, indicating that you are ready to proceed with Docker integration.

Containers

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

To access this 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 initiate a new container deployment.

To efficiently locate available images, utilize the search box. You can specify the image name, the repository, or a combination of both to refine your search results. The following repositories are available for searching:

• Local repository: This contains images that have already been downloaded and are now stored directly on the server hosting Docker. For more detailed information, refer to the Managing Local Images section later in this document.
• Docker Hub: The official public registry for Docker images.

It's important to note that multiple versions may be available for each application. You can execute a specific version by carefully selecting the appropriate tag from the options provided.

To run a container effectively, follow these steps:

1. Navigate to Docker > Containers > Run Container.
2. Use the search box to locate desired images within the catalog. If an image is stored locally, it will be clearly indicated with (local) appearing after its version.
3. To view a comprehensive 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 deploy.

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

   Plesk will then initiate the creation of a container and prompt you to specify its various settings, such as environment variables, before running it. You have the option to cancel the running process by clicking Cancel on the Settings screen. For a comprehensive understanding of these settings, refer to the Container Settings section presented later on this page.

5. After meticulously adjusting the settings to your requirements, click Run. The newly launched container will subsequently appear in the list of containers located within the Containers tab.

Always review the Console Log to ascertain if the container is running without any issues or unexpected behaviors.

Container Settings

Note: If you need to modify container settings, it is not necessary to stop the container beforehand. When you save new settings, Plesk intelligently recreates the container to apply the changes.

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

Limiting Memory

By default, the utilization of RAM within a Docker container is unrestricted. To enforce a limit on RAM usage, select the Memory limit checkbox and then input the desired limit value, in megabytes, into the MB field.

Note: Currently, CPU and Disk usage cannot be limited for Docker containers. Additionally, Docker containers are considered administrator-level objects and are therefore not governed by subscription-level cgroup limits pertaining to CPU, RAM, or Disk usage.

Automatic Start

If the option Automatic start after system reboot is not enabled, any websites relying on this container might become inaccessible following 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 activated, which automatically maps the container's internal port to a randomly assigned port on the host system (for example, port 32768).

To manually alter 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 employing manual mapping, Docker, by default, only binds to the specified port on the host system’s localhost interface (127.0.0.1). This configuration inherently makes the port inaccessible from the Internet, thereby safeguarding the application within the container from external attacks. To instruct 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 enabling this option will make the application inside the container publicly accessible from the Internet, allowing it to 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 instance, MySQL/MariaDB typically disallows anonymous access by default, whereas Redis permits it). Exposing an application inside a container directly to the Internet without proper authentication can potentially leave it vulnerable to malicious attacks.

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 reliably accessed from your host system. Crucially, the data residing in Docker volumes is not deleted when you stop or even remove a container.

Warning: Data stored within Docker volumes will not be included in standard Plesk backups. To prevent potential data loss, it is highly recommended to back up any essential data residing in a volume using a third-party backup solution.

For more in-depth information concerning data management within 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: Provide the absolute path to a directory situated inside the container.

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 suit your application's requirements. Plesk offers the flexibility to add as many environment variables as necessary for optimal container operation.

Operations with Containers

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

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

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

• Click the arrow icon adjacent to the container to view detailed logs and monitor its resource consumption.
• Click the settings icon next to the container to conveniently modify its settings, such as environment variables or volume mapping (Settings).
• Rename a container by navigating to its settings (Settings) and editing the Container name field.

To access additional advanced options, click the more options icon next to the container. From this menu, you can perform one or more of the following actions:

• Recreate a container, either using the identical image version or an alternative version available in the catalog (Recreate).
• Create a new image based on your existing container, incorporating any custom settings you have applied (Save as Image).
• Generate and download a snapshot of the container's current state (Download Snapshot).
• Permanently remove a container from your system (Remove).

Recreating a Container

The recreation of a container is typically necessary when you aim to update the application to a newer version. However, you are not limited to newer versions; you can rebuild a container using any application version available within the Docker catalog.

It's important to note that custom settings applied to the container are meticulously preserved during the recreation process. To ensure the preservation of data utilized by the application inside a container, it is highly advisable to configure volume mapping before initiating a container recreation. Volume mapping facilitates persistent access to directories used within a container, as detailed in the Volume Mapping section of the container settings.

To recreate a container, follow these steps:

1. Navigate to Docker and click the more options icon situated next to the container you intend to recreate.
2. Click Recreate within the container settings. You will then be prompted to specify the desired image version and to confirm whether to use default environment variables or your custom configurations.

Using Remote Docker

By default, Plesk is configured to utilize Docker installed as a local service on the same server. However, for enhanced flexibility and scalability, you have the option to employ one or more Docker services that are installed on external, remote machines. It is important to remember that only one Docker service can be active at any given time. The currently active server is always displayed 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 use a remote server as a Docker host within Plesk, you must configure it as described in the official Docker documentation, specifically regarding secure access.

Managing Remote Services

Establishing a secure connection between a Plesk server, equipped with the Docker extension, and a remote node running a Docker service is a straightforward process. The following steps are applicable to both Plesk for Linux and Plesk for Windows environments.

These essential 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 utilize 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 the host system's 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 contain critical information required by the client to establish a remote connection:

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

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

1. Navigate to Docker > Environments.
2. Click Add Server and meticulously specify all required settings for the remote server hosting 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 be prominently displayed in the Navigation Pane.

To switch between different Docker services:

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

Creating Images with Custom Settings

Should you wish to generate a new Docker image based on modifications you have applied to an existing container, utilize the Save as Image command. This action effectively captures a snapshot of your container's current state, which then appears as a new, customized image within your image catalog. This functionality is particularly useful for creating images pre-configured with specific settings, such as tailored environment variables.

To create a custom image from one of your containers, follow these steps:

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

• The desired Image name.
• An optional Tag, where you can specify the image version. By default, if no tag is provided, the version will be designated as "latest".

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

Managing Local Images

Local images are Docker images that are permanently stored on your local disk, eliminating the need to download them repeatedly from the online Image Catalog.

An image becomes designated as local under several circumstances:

• When you select any version (tag) of an image and the download process commences. Even if you subsequently run a container or cancel the operation on the Settings screen, the image remains saved locally.
• When you 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, as described in the Creating Images with Custom Settings section.
• When you have built an image using the command-line interface.

To download an alternative version of an image from the online catalog, click the Pull icon, choose the specific version you wish to pull from the drop-down menu, and then click Pull.

If Docker has at least one downloaded version from a group of versions belonging to a particular image, that image will be labeled as a Local image in the catalog. Plesk also conveniently indicates how many local images exist for a given product.

To view and efficiently remove outdated local images, follow these steps:

1. Navigate to Docker > Images.
2. To locate a specific local image, utilize the Search bar.
3. To view all local images associated with a particular product, click the link displayed beneath 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 ports, enabling applications running within them to be accessible through these specified ports.

When integrating an application within a Docker container into your website, you might find it inconvenient to always specify a non-standard port in its URL. To enhance user experience and simplify access, you can configure nginx to proxy requests from your domains to that specific container port. This allows domains to utilize a standard port, such as 80 or 443, eliminating the necessity to explicitly include the port number 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 the host system (e.g., 32768).

To manually map the port inside a container:

1. Go to Docker > Containers and click the settings icon next to the container you intend to modify.
2. Deactivate Automatic port mapping.
3. Manually map the port internal to the container to a distinct port on your host system (for example, 32768). You have the option to configure this host port to be 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. This setup allows your domains to operate on a standard nginx port (e.g., 80 or 443). To enable this, you need to add a proxy rule for nginx within your domain settings.

To add a rule for nginx in the domain settings:

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

• 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 Docker container application you wish to integrate.
• Port: Choose one of the port mappings that was previously defined in the container settings (specifically, a port inside the container mapped to a port on your host system). Nginx will then proxy 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's worth noting that proxy rules are generally designed to function effectively on servers operating 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 rule occurs when a website directory is mounted to a Docker container as a volume; in such cases, all files located within the container will be counted towards the disk space usage of the website.

Deploying Docker Compose YAML files

Plesk facilitates the deployment of Docker Compose YAML files through multiple convenient methods: using an integrated online text editor, uploading a file from your local storage, or by selecting a Docker Compose file already stored within a website’s Home directory. Standard operations for managing stacks are fully supported, including `up` (which encompasses `pull` and `force-recreate`), `stop`, and `down`. Furthermore, you retain the flexibility to modify and update your deployed stacks even after their initial creation.

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

To deploy a Docker Compose file, follow these steps:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a unique project name and then choose one of the available 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 storage.
   • Webspace: Select a Compose file that is already stored within a domain’s Home directory. For this option, you will first choose the relevant domain where the file is located, and then browse to the Compose file's exact location.

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

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

Deploying Portainer containers in Docker

Portainer is a powerful and intuitive container management software designed to simplify the deployment of containers and stacks, provide real-time visibility into container status and logs, facilitate user and team creation, and enhance the security of your Docker environments, among other features.

To install Portainer, simply 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 integration within Plesk is currently offered as a beta feature.

For more extensive information about Portainer's functionalities and usage, refer to the official Portainer documentation.