Using Docker with Plesk Obsidian

Docker represents a robust platform designed for running applications within isolated containers. This technology empowers users to deploy specific software, such as Redis or MongoDB, or particular versions of applications that might not be natively supported by their operating system or could require complex compilation processes.

Within the Plesk environment, Docker is seamlessly integrated as an extension. This integration allows you to efficiently run and manage containers derived from various Docker images, utilizing Docker capabilities on both your local host and connected remote servers.

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 remote Docker hosts from your Plesk interface, ensuring a streamlined and powerful container management experience.

Requirements and Limitations

Warning: The Docker extension directly downloads images from Docker Hub without any pre-configuration. It's crucial to understand that some Docker containers and their embedded software are designed for trusted environments only and may necessitate additional security configurations. Before deploying any downloaded images within Plesk, you are responsible for implementing necessary security enhancements. For detailed instructions, always refer to the official documentation provided by the container or software vendor. As an example, consult the security section in the Redis documentation.

To ensure optimal operation and compatibility, please be aware of the following requirements and limitations when using Docker in Plesk:

• Docker is officially supported in Plesk for a wide range of operating systems, including 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 any later version. For Plesk on Windows, you have the option to utilize Docker installed on a remote machine, as detailed in the Using Remote Docker section of this guide.
• It is not possible to deploy Docker within a Plesk instance that is itself running inside a Docker container.
• Accessing and managing remote Docker services through Plesk requires an additional license. This essential license can be acquired either separately or as part of a comprehensive bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker is exclusively designed to operate on x64 based systems.
• Direct migration or backup of Docker containers within Plesk is not supported. However, it is possible to back up the data utilized by these containers (refer to the Volume Mapping below), or to download snapshots for recovery purposes.
• Virtuozzo 7, specifically with Update 1 Hotfix 1 (7.0.1-686) or a subsequent update, is fully supported. It's important to note that with this update and all newer versions, any new containers based on CentOS 7 will have 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 and accessible.

Prerequisites

Before you can begin leveraging the capabilities of Docker within Plesk, it is essential that the Docker extension is properly installed on your Plesk server. This installation is a fundamental step to enable Docker functionality.

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

Once the Docker extension has been successfully installed, your Plesk environment will be prepared for Docker integration. You will then observe the dedicated "Docker" option appearing conveniently in the Navigation Pane, ready for you to explore and manage your containers.

Managing Docker Containers

Plesk provides a straightforward interface to access and deploy Docker images from Docker Hub directly within its "Run Container" catalog. Navigate to Docker > Containers > Run Container to begin.

Accessing the Container Catalog

To access the comprehensive catalog of Docker images:

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

Once in the catalog, utilize the search box to efficiently find available images. You can specify the image name, the repository, or a combination of both to narrow down your results.

Understanding Repositories

The following repositories are available for your search queries:

• Local repository: This contains images that have already been downloaded and are stored on your server, managed by Docker. For more in-depth information, refer to the Managing Local Images section later in this guide.
• Docker Hub: The official cloud-based registry service provided by Docker, offering a vast collection of public and private images.

Many applications within Docker Hub offer multiple versions. You have the flexibility to run a specific version by selecting the appropriate tag during the deployment process.

Steps to Run a Container

Follow these steps to successfully deploy and run a Docker container:

1. Navigate to Docker > Containers > Run Container.
2. Use the search box to locate your desired images within the catalog. If the image is already stored locally on your server, the label (local) will appear next to its version.
3. To review the image's description and access its official documentation on Docker Hub, click the "more info" icon. Please note that this option is not applicable to local images.
4. Click on the desired image card to proceed.
   • To deploy a specific version of the image, select the desired version from the Image version drop-down menu and then click Next.
   • To deploy the latest available version of the chosen application, simply click Next.

   Plesk will then initiate the creation of the container and present you with a settings screen where you can configure various parameters, such as environment variables. The container will then run with your specified settings. You have the option to cancel this process at any point by clicking Cancel on the Settings screen. For a comprehensive overview of these configurations, please refer to the Container Settings section provided later on this page.

5. After carefully adjusting and confirming your settings, click Run. The newly deployed container will then appear in the list displayed within the Containers tab.

Always review the Console Log to ascertain whether the container is operating as expected and without any issues.

Container Settings

It's important to note that when you modify container settings, there's no need to stop the container beforehand. Plesk intelligently handles these changes by recreating the container with the updated settings automatically.

To access and modify the settings for a specific container, navigate to the Containers tab and click the settings icon (often represented by a gear or wrench symbol) located next to the container you wish to configure.

Limiting Memory Usage

By default, Docker containers in Plesk operate without a predefined RAM usage limit. To impose a restriction on the amount of RAM a container can consume, simply select the Memory limit checkbox and then input the desired limit value in megabytes (MB) into the corresponding field.

Note: At present, resource limitations for CPU and Disk usage are not available for Docker containers within Plesk.

Note: Docker containers are managed as administrator-level objects. Consequently, their resource consumption is not governed by subscription-level cgroup limits, which typically control CPU, RAM, and Disk usage for other services.

Automatic Start Configuration

The Automatic start after system reboot option determines the container's behavior following a system restart. If this option is not selected, any websites or services that rely on this particular container might become unavailable after a system reboot, necessitating a manual restart of the container.

Port Mapping Management

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., port 32768). This provides immediate network access for the container.

To establish a specific port on the host system, deselect Automatic port mapping and then specify your preferred external port in the Manual mapping field. If the Manual mapping option does not appear after deselecting automatic mapping, it indicates that the container is not configured to expose any ports.

When employing manual mapping, Docker, by default, binds the specified port exclusively to the host system’s localhost interface (127.0.0.1). This configuration inherently restricts external access, thereby enhancing the security of the application running inside the container by making the port inaccessible from the internet. To enable Docker to bind to the specified port across all network interfaces of the host system, deselect the Make the port inaccessible from the Internet option. Choosing this will make the application within the container publicly accessible via the specified port through any of the host system’s assigned IP addresses.

Warning: Docker's design often assumes that authentication mechanisms are handled directly by the application itself. However, this is not always the case (for instance, while MySQL/MariaDB typically disallows anonymous access by default, Redis may permit it). Making an application within a container accessible from the internet without proper, application-level authentication can expose it to significant security vulnerabilities and potential attacks from malicious actors. Always ensure robust security measures are in place.

Volume Mapping for Persistent Data

Docker volumes are crucial for persistent storage within containers. These are essentially directories on your server that are mounted directly into a Docker container, providing a mechanism for data to persist independently of the container's lifecycle. Data stored within Docker volumes remains intact even when a container is stopped, deleted, or recreated.

Warning: It is critical to understand that data stored within Docker volumes will not be included in standard Plesk backups. To prevent any data loss for essential information residing in a volume, it is highly recommended to implement a third-party backup solution specifically for these volumes.

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

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

• 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: Provide the absolute path to the directory inside the Docker container where the host directory will be mounted.

Should you need to map additional directories, simply click the Add one more button to include further volume mappings.

Setting Environment Variables

Environment variables serve as critical configuration parameters utilized by the application running inside a container. Plesk offers the flexibility to add new variables or modify existing ones as required by your application. You can define as many environment variables as your containerized application demands.

Operations with Containers

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

• You can easily control the runtime state of your containers by using the Stop, Start, or Restart actions. It is important to remember that in all these cases (stopping, starting, or restarting), the container will be recreated with its current configuration settings.

  Note: If you have not configured persistent storage by saving data to mounted volumes, any unsaved data will be lost when the container is recreated.

• To monitor the performance and health of your containers, click the arrow icon (typically an expand/collapse arrow) adjacent to the container name. This will reveal detailed logs and real-time resource consumption statistics.
• To modify a container's configuration, such as environment variables or volume mappings, click the settings icon (gear symbol) next to the container to access its Settings interface.
• You also have the ability to rename a container for better organization. This can be done within its Settings panel, under the Container name option.

For more advanced container management actions, click the "more options" icon (often represented by three dots or a hamburger menu) located next to the container. From this menu, you can perform one or more of the following operations:

• Recreate: This allows you to rebuild a container, either using the exact same image version or upgrading/downgrading to a different one.
• Save as Image: Create a new Docker image based on the current state and custom settings of your container. This is ideal for creating custom base images.
• Download Snapshot: Generate and download a snapshot of your container, useful for backup or migration purposes.
• Remove: Permanently delete a container from your Plesk environment.

Recreating a Container

The recreation of a container is a common operation, particularly when you intend to update a containerized application to a newer version. However, this functionality is not limited to upgrades; you can rebuild a container using any application version available within the Docker catalog, offering flexibility for both updates and rollbacks.

A significant advantage of the recreation process in Plesk is that all your custom container settings are automatically preserved. To ensure the integrity and persistence of data utilized by the application inside a container, it is crucial to establish volume mapping prior to initiating a recreation. Volume mapping provides a direct link to directories within the container, safeguarding your application's data across recreations.

To recreate an existing container, follow these steps:

1. Navigate to Docker in your Plesk navigation panel. Then, locate the container you wish to recreate and click on the "more options" icon (typically three vertical or horizontal dots) adjacent to it.
2. From the options presented, select Recreate. You will then be prompted to specify the desired image version for the new container and to confirm whether you wish to utilize the default environment variables or your custom settings.

Utilizing Remote Docker Hosts

While Plesk defaults to managing a locally installed Docker service, it also offers the capability to integrate with one or more Docker services deployed on external, remote servers. It is important to remember that only one Docker service can be actively managed by Plesk at any given time. The currently active server can be identified within the Environments tab on the Docker settings page in Plesk.

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

Configuring Remote Services

To prepare your remote server for integration with Plesk, it must be configured to run Docker as a remote service. Please refer to the detailed instructions provided in the official Docker documentation on engine security and HTTPS for proper setup.

Managing Remote Services in Plesk

Plesk facilitates the establishment of a secure connection between your Plesk server (equipped with the Docker extension) 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 the Docker configuration file, /etc/docker/daemon.json, and populate it with the following content. This configuration enables TLS and specifies the host addresses for Docker communication:

   {
     "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. Generate the necessary .pem certificate files for secure communication. You can use the following OpenSSL commands as an example. Remember to replace the IP address on line 4 with the actual IP address of your remote Docker 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. Execute the following commands to modify the systemd service file for Docker, ensuring that the Docker service starts correctly after the host configuration has been applied:

   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. For the client (your Plesk server) to connect to the remote Docker host, you must save the outputs of the following certificate files onto your local machine:

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

Configuring the Docker Remote Host on the Local Plesk Server:

1. Access the Docker interface in Plesk by navigating to Docker > Environments.
2. Click on the Add Server button and then provide the required settings for your remote Docker server.
3. To immediately begin using this remote Docker service within Plesk, ensure that the Set active option remains selected.

Upon successful configuration, the link to the Docker management interface will become visible within the Navigation Pane of your Plesk control panel.

Switching Between Docker Services:

If you have multiple Docker services configured (both local and remote), you can easily switch between them:

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

Alternatively, this activation can also be performed conveniently while you are in the process of editing the settings for a particular Docker node.

Creating Custom Docker Images from Containers

When you have made specific modifications or configurations to a running container and wish to preserve these changes as a new, reusable Docker image, the Save as Image command is your essential tool. This operation effectively captures a snapshot of your container's current state, which then registers as a new image within your Docker image catalog. This method is particularly useful for establishing custom images pre-configured with specific settings, such as unique environment variables, eliminating the need to reapply them manually each time.

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

1. Navigate to Docker > Containers.
2. Locate the container from which you intend to create an image, click on the "more options" icon (e.g., three dots) next to it, and then select the Save as Image option.
3. A side panel titled "Save <container name> as Image" will appear. Within this panel, you will need to specify:
   • Image name: A descriptive name for your new custom image.
   • Tag (optional): An optional tag allows you to denote the image version. By default, if no tag is provided, the image will be labeled as "latest".

Once created, your new image will be listed in the Images tab and distinctly marked as a Local image, indicating it is stored on your server.

Managing Local Docker Images

Local images are Docker images that reside directly on your server's local storage. These images are readily available for deployment without requiring a download from the online Image Catalog, significantly speeding up container deployment.

An image transitions to a local status under several common scenarios:

• When you select any version (tag) of an image from the catalog and the download process commences. Even if you subsequently run a container or cancel the operation on the Settings screen, the image will be retained locally.
• Upon successfully uploading an image to Docker within Plesk, using the Upload image option located in the Docker Images tab.
• When you construct a custom image directly from an existing container, as detailed in the section on Creating Custom Docker Images from Containers.
• If an image has been built directly through the command-line interface on your server.

To acquire an alternative version of an image from the online catalog, simply click the Pull icon (often represented as a download or pull symbol), select your desired version from the accompanying drop-down menu, and then click Pull.

Should Docker have at least one version of an image group downloaded and stored locally, that image will be prominently marked as a Local image within the catalog. Plesk conveniently displays the total count of local images associated with a particular product.

Viewing and Removing Outdated Local Images

To effectively manage your local image repository and remove any outdated or unnecessary images, follow these steps:

1. Navigate to Docker > Images in your Plesk control panel.
2. Utilize the Search bar to quickly locate a specific local image you are looking for.
3. To gain a comprehensive view of all local images pertaining to a particular product, click on the link provided directly beneath the product name. This will display all associated local image tags and their respective occupied disk space.
4. Select the individual image(s) you wish to remove, and then click the Remove button to permanently delete them from your local storage.

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 those designated ports. However, when integrating such an application with your website, it can be inconvenient for users to constantly specify a non-standard port in the URL.

To mitigate this inconvenience and provide a more user-friendly experience, you can configure Nginx to proxy incoming requests from your domains directly to the container's exposed port. This setup enables your domains to utilize a standard web port (such as 80 or 443), eliminating the need for users to explicitly include the port number in the URL.

Prerequisites for Nginx Proxying

Before proceeding with Nginx proxy configuration, ensure that the following conditions are met:

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

Steps to Manually Map a Container Port:

1. Navigate to Docker > Containers, and then click the settings icon next to the container you wish to configure.
2. Deactivate the Automatic port mapping option.
3. Manually assign the container's internal port to a precise port on your host system (e.g., 32768). For enhanced security, you have the option to make this host port inaccessible from the Internet.

Once the container port is manually mapped, you can proceed to configure Nginx to proxy requests from your domains to this host port, thereby allowing your domains to operate on standard web ports like 80. To enable this, a specific Nginx rule must be added within your domain's settings.

Adding an Nginx Proxy Rule in Domain Settings:

To establish an Nginx proxy rule, perform the following steps:

1. Go to Websites & Domains > [select your domain] > Docker Proxy Rules > Add Rule.
2. You will then need to specify the following details:
   • URL: Define the URL path of your website that utilizes the application running within the Docker container. This can be for the entire main website or a specific section of it.
   • Container: Select the Docker container that hosts the application you wish to proxy to.
   • Port: Choose one of the port mappings that was previously defined in the container's settings (i.e., an internal container port mapped to a specific port on your host system). Nginx will then direct requests to this designated host system port.

These proxy rules are seamlessly integrated into your web server configuration, typically within the website’s nginx.conf file, which can be found at a path similar to /var/www/vhosts/system/$domain/conf/. An example of such a rule might look 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 Nginx proxy rules are designed to function reliably even on servers operating behind a Network Address Translator (NAT).

Note: Docker containers that are connected to a website via Proxy Rules typically do not contribute to the subscription’s disk space usage calculation. An important exception occurs if a website directory is mounted as a volume into a Docker container; in this specific scenario, all files located within that container will be factored into the website's total disk space usage.

Deploying Docker Compose YAML Files

Plesk simplifies the deployment of multi-container Docker applications by supporting Docker Compose YAML files. You have several flexible methods to deploy these files: using an integrated online text editor, uploading a file directly from your local storage, or leveraging a Docker Compose file already present within a website’s Home directory. Plesk supports essential stack operations, including up (which encompasses pull and force-recreate functionalities), stop, and down. Furthermore, you retain the ability to modify and update your deployed stacks post-creation.

Note: This specific section of Plesk is dedicated solely to Docker Compose YAML files. It does not support the deployment of Dockerfiles or any other auxiliary files required by your application.

To initiate the deployment of a Docker Compose file, follow these steps:

1. Navigate to Docker > Stacks > Add Stack.
2. Provide a unique project name for your stack. Then, select your preferred method for deploying the Docker Compose file:
   • Editor: This option allows you to define or paste the content of your Docker Compose file directly into an integrated text editor.
   • Upload: Choose this method to upload a Docker Compose file from your local computer storage.
   • Webspace: If your Docker Compose file is already stored within a domain’s Home directory, select this option. You will then need to choose the specific domain where the file is located and browse to the exact location of your Compose file.

Plesk also enables you to declare and build custom containers as part of your Docker Compose stack. Any artifacts generated during this build process will be conveniently placed within the designated website’s Home directory.

For in-depth details about 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 significantly streamline the deployment and administration of containers and stacks. It offers a user-friendly interface for various tasks, including monitoring container status and logs, establishing user accounts and teams, securing your containerized environments, and much more.

To install Portainer within your Plesk Docker environment, simply navigate to Docker > Install Portainer. Once the installation process is successfully completed, you can access and manage your Portainer containers directly through Plesk by going to Docker > Go to Portainer.

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

For comprehensive details and advanced usage instructions regarding Portainer, please refer to the official Portainer documentation.