Using Docker in Plesk Obsidian

Requirements and Limitations

Warning: The Docker extension directly downloads images from Docker Hub without any pre-configuration. Some Docker containers or software contained within them are designed for trusted environments only and may necessitate additional security measures. Before deploying these downloaded images in Plesk, it is essential to enhance their security yourself. For detailed instructions, please consult the documentation provided by the container or software vendor. For instance, refer to the security section in the Redis documentation.

To ensure smooth operation, please be aware of the following requirements and limitations when utilizing Docker within Plesk:

• 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, you have the option to use Docker installed on a remote machine. Detailed instructions can be found in 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. This configuration is not supported.
• Accessing remote Docker services through Plesk requires an additional license. This license can be acquired separately or as part of a bundle such as the Hosting Pack, Power Pack, or Developer Pack.
• Docker is exclusively designed to run on x64 systems, meaning 32-bit architectures are not supported.
• Docker containers managed within Plesk cannot currently be migrated or backed up directly using Plesk's native backup features. However, you can back up the critical data utilized by containers by leveraging Volume Mapping, or you can download snapshots of your containers.
• 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, a change implemented by Virtuozzo to enhance security. 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 within Plesk, it is mandatory to have the Docker extension installed on your Plesk server. Follow the relevant steps below:

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

Once the extension has been successfully installed, you will find the "Docker" option conveniently located in the Navigation Pane, indicating that you are ready to explore and utilize Docker functionality.

Managing Containers

Plesk provides a streamlined interface to access and manage Docker images directly from Docker Hub. The "Run Container" catalog, accessible via Docker > Containers > Run Container, is your gateway to a vast collection of applications.

To open the container catalog:

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

You can efficiently find available images by using the search box. Specify the image name, the repository, or a combination of both to narrow down your results.

The following repositories are available for your search:

• Local repository: This contains images that have already been downloaded and are stored on your server, making them readily available without needing to connect to external registries. For more information, refer to the Managing Local Images section below.
• Docker Hub: The world's largest library and community for container images.

For many applications, multiple versions (or tags) are available. You can run a specific version by carefully selecting the appropriate tag from the options presented.

To run a new container, follow these steps:

1. Go to Docker > Containers > Run Container.
2. Use the search box to locate the desired images within the catalog. If an image is already stored locally on your server, (local) will appear next to its version.
3. To view the full description and documentation for an image on Docker Hub, click the "more info" icon. This option is not applicable for local images.
4. Click on the image card corresponding to the application you wish to deploy.
   • To deploy a specific version of the application, select your preferred image version from the Image version drop-down menu and then click Next.
   • To deploy the very latest version of the chosen application, simply click Next.
5. Plesk will then proceed to create a new container and present you with a screen to specify its settings, such as environment variables. The container will run after configuration. You can choose to cancel this process by clicking Cancel on the Settings screen. For a comprehensive understanding of these settings, please refer to the Container Settings section on this page.
6. After you have configured and fine-tuned the settings to your requirements, click Run. The newly created container will then appear in the list within the Containers tab.

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

Container Settings

Configuring your Docker containers is crucial for their optimal performance and security. Plesk allows you to easily modify container settings even without stopping them; when you save new settings, Plesk gracefully recreates the container to apply your changes.

To access and edit container settings, navigate to the Containers tab and click the settings icon next to the container you intend to modify.

Limiting Memory

By default, Docker containers operate with an unlimited amount of RAM access, which can be inefficient for resource management. To impose a limit on RAM usage, select the Memory limit checkbox and input the desired limit value in megabytes (MB) into the corresponding field. This helps in preventing a single container from consuming excessive system resources.

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

Note: Docker containers are considered administrator-level objects. Consequently, they are not subject to the subscription-level cgroup limits that typically apply to CPU, RAM, and disk usage for other services.

Automatic Start

The Automatic start after system reboot option determines whether your container will automatically restart after the server reboots. If this option is not selected, any websites or services that rely on this container may experience downtime after a system reboot, requiring you to manually start the container to restore functionality.

Port Mapping

By default, Automatic port mapping is enabled. This feature automatically maps the container’s internal port to a randomly assigned port on the host system (for example, port 32768). This provides a quick and easy way to get your container running.

Should you need to assign a specific port on the host system, deselect Automatic port mapping and then specify your desired external port in the Manual mapping field. If the Manual mapping option does not appear after deselection, it indicates that the container has not been configured to expose any ports.

When employing manual port mapping, Docker, by default, binds the specified port exclusively to the host system’s localhost interface (127.0.0.1). This configuration inherently makes the port inaccessible from the public Internet, significantly enhancing the security of the application running inside the container by shielding it from external attacks. To make the application accessible from the Internet, you must deselect Make the port inaccessible from the Internet. Doing so will bind the specified port to all network interfaces of the host system, making the application accessible on that port via any of the host system’s IP addresses.

Warning: While Docker assumes that authentication is handled by the application itself, this is not always the case (e.g., MySQL/MariaDB typically requires authentication 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 malicious actors and potential attacks. Always ensure your application has robust security in place.

Volume Mapping

Docker volumes are essentially directories on your host server that are mounted directly into a Docker container. This mechanism is vital for achieving persistent storage, allowing data to persist even if the container is stopped, removed, or recreated. Data stored within Docker volumes remains intact independently of the container's lifecycle.

Warning: It is crucial to understand that data stored in Docker volumes will not be included in Plesk's standard backup procedures. To safeguard against data loss, it is strongly recommended to back up any essential data residing in a volume using a reliable third-party backup tool or strategy.

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

To establish a volume mapping, you need to specify two paths:

• In the Host field, provide the absolute path to the directory on your server that you wish to mount into the container.
• In the Container field, provide the absolute path to the target directory inside the container where the host directory will be mounted.

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

Setting Environment Variables

Environment variables play a critical role in configuring the application running inside a container. You may often need to introduce 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, allowing for granular control over its runtime environment.

Operations with Containers

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

• You can easily Stop, Start, or Restart a container using the respective buttons. In each of these cases, the container will be recreated based on its current configuration settings.

  Note: If you have not configured Volume Mapping to save persistent data, any unsaved data within the container will be lost when it is stopped or recreated.

• Clicking the arrow icon next to a container will reveal its logs and current resource consumption, offering valuable insights into its operation and health.
• To adjust a container's settings, such as environment variables or volume mappings, click the settings icon next to it. This takes you to the Settings interface.
• You can easily rename a container by navigating to its settings (Settings > Container name) and entering a new descriptive name.

For more advanced actions, click the "more options" icon next to the container to access additional functionalities:

• Recreate: Rebuild a container using the same image version or upgrade/downgrade to an alternative version available in the catalog.
• Save as Image: Create a new Docker image based on the current state and custom settings of your container.
• Download Snapshot: Generate and download a snapshot of your container at a specific point in time.
• Remove: Permanently delete a container from your system.

Recreating a Container

Recreating a container is a common procedure, particularly when you need to update the application within it to a newer version. However, this functionality is versatile, allowing you to rebuild a container using any application version available in the Docker catalog, not just newer ones.

All custom settings you have applied to the container are meticulously preserved during the recreation process. To safeguard the data used by the application inside the container, it is imperative to configure Volume Mapping before initiating a container recreation. Volume mapping ensures that directories used inside the container are accessible from the host system, providing data persistence.

To recreate a container:

1. Go to Docker and click the "more options" icon next to the container you wish to recreate.
2. Click Recreate in the container settings panel. You will then be prompted to specify the desired image version and whether to utilize default environment variables for the new container instance.

Using Remote Docker

By default, Plesk integrates with the Docker service installed locally on the Plesk server. However, for enhanced flexibility and scalability, you have the option to leverage one or more Docker services installed on remote machines. It's important to note that you can only have one Docker service active within Plesk at any given time. The currently active server is clearly indicated in the "Environments" tab of the Docker settings page.

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 that runs directly on the Plesk server.

Configuring Remote Services

Before you can add a remote Docker server to Plesk, you must properly configure the remote machine where Docker is running. This configuration primarily involves securing the Docker daemon to accept remote connections securely, as detailed in the official Docker documentation on securing the daemon with HTTPS.

Managing Remote Services

Plesk facilitates establishing a secure connection between your Plesk server (with the Docker extension installed) and a remote node hosting a Docker service. The following instructions are applicable for both Plesk for Linux and Plesk for Windows installations.

These steps must be performed on the remote host:

1. Create or modify the `/etc/docker/daemon.json` configuration file for your Docker installation with the following content. This configuration enables TLS for secure communication and specifies the host interfaces Docker should listen on.

   {
     "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` certificate files for TLS 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, and execute each command sequentially. This process generates a Certificate Authority (CA), server certificates, and client certificates for secure connection.

   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 Docker service configuration, ensuring it starts correctly after host configuration and system reboots. This involves copying the service file, adjusting its startup parameters, and reloading the system daemon.

   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 from your remote machine to your local machine. These certificate files (`key.pem`, `cert.pem`, `ca.pem`) are essential for the Plesk client to establish a secure remote connection to the Docker daemon.

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

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

1. Go to Docker > Environments.
2. Click Add Server and provide the necessary settings for your remote Docker server, including the host details and the certificate files you copied.
3. To immediately begin using this remote Docker service within Plesk, ensure that the Set active option is selected during the configuration process.

Once configured, a link to the active Docker environment will appear in the Navigation Pane, providing quick access.

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 wish to activate and click Set Active.

Alternatively, you can designate a Docker node as active directly while you are in the process of editing its settings.

Creating Images with Custom Settings

When you make modifications to a Docker container and wish to preserve those changes for future deployments, you can create a new image based on your customized container. The Save as Image command allows you to take a snapshot of your current container's state, which then appears as a brand-new image in your image catalog. This feature is particularly useful for creating reusable images with predefined custom settings, such as specific environment variables or configurations.

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

Navigate to Docker > Containers, then click the "more options" icon next to the container you want to save as an image. Select Save as Image. In the "Save <container name> as Image" side panel, you will need to specify the following:

• Image name: A descriptive name for your new custom image.
• Optional Tag: You can assign a specific version or tag to this image (e.g., "v1.0", "staging"). By default, if no tag is specified, it will be labeled as "latest".

The newly created image will then be listed in the "Images" tab and distinctly marked as a Local image, signifying it's stored on your server.

Managing Local Images

Local images are Docker images that are stored directly on your server's local disk. The primary advantage of local images is that they eliminate the need to download them from external registries like Docker Hub every time you want to deploy a container, leading to faster deployment times and reduced bandwidth usage.

An image becomes a local image under several circumstances:

• When you initiate a download of any version (tag) of an image from the catalog. Even if you cancel the container creation process at the "Settings" screen, the image data is still saved locally.
• If you manually upload an image to Docker within Plesk using the Upload image function in the Docker "Images" tab.
• When you create a custom image from an existing container, as described in the Creating Images with Custom Settings section.
• If you have built an image using the Docker command-line interface directly on the server.

If Docker detects that at least one version from a group of an image's available versions is stored locally, that image will be labeled as Local image in the catalog. Plesk also conveniently displays the number of local images that exist for a particular product.

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

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

1. Go to Docker > Images.
2. Utilize the Search bar to quickly find a specific local image if your list is extensive.
3. To view all local images associated with a particular product, click the link displayed under the product name. This will show all local image tags and the disk space they currently occupy.
4. Select the specific image(s) you wish to remove and click Remove to free up disk space.

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 via those ports. However, directly accessing applications through non-standard ports in a URL (e.g., yourdomain.com:32768) can be inconvenient for users.

Plesk allows you to configure Nginx to proxy requests from a domain to a container's exposed port. This means users can access your application via a standard port (like 80 or 443), while Nginx intelligently forwards the requests to the correct internal container port, providing a seamless user experience.

Requirements

• Nginx must be actively running and enabled within your Plesk environment.
• You must have manually mapped the internal port of your Docker 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 wish to configure.
2. Turn off the Automatic port mapping option.
3. Manually map the internal port of the container to a specific port on your host system (for instance, 32768). You have the option to make this host port inaccessible from the Internet for added security.

Once the port is manually mapped, you can set up Nginx to proxy requests. This allows your domains to utilize a standard port on Nginx (e.g., 80) without explicitly specifying the container's host port. To achieve this, you need to add a proxy rule within your domain's settings.

To add a proxy rule for Nginx in the domain settings:

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

• URL: Define the URL of your website or a specific part of it that will serve the application running in the Docker container. This can be the main domain or a subdomain/path.
• Container: Select the Docker container that is running the application you want to proxy requests to.
• Port: Choose one of the port mappings that you previously configured in the container settings (i.e., the port inside the container mapped to a specific port on your system). Nginx will then proxy requests to this specified port on your host system.

These proxy rules are implemented within the web server configuration, typically found in the website's `nginx.conf` file (e.g., located at `/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 these proxy rules are designed to function effectively on servers operating behind Network Address Translation (NAT) configurations.

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 to this rule is when a website directory is explicitly mounted to a Docker container as a volume. In such a scenario, all files located within that container will be counted towards the disk space usage of the associated website.

Deploying Docker Compose YAML Files

Docker Compose is a powerful tool for defining and running multi-container Docker applications. Plesk seamlessly integrates with Docker Compose, allowing you to deploy your applications defined in YAML files with ease. You have multiple methods for deploying these files:

• Utilizing the online text editor to directly define or paste the content of your Compose file.
• Uploading a Compose file from your local storage.
• Selecting a Docker Compose file that is already stored within a website's Home directory on your server.

Plesk supports typical operations on Docker Compose stacks, including `up` (which encompasses `pull` and `force-recreate` for updating services), `stop` to halt services, and `down` to stop and remove containers, networks, and volumes defined in the Compose file. Furthermore, you retain the flexibility to modify and update your deployed stacks after their initial creation.

Note: This section of Plesk is specifically for deploying Docker Compose YAML files. It does not support the deployment of Dockerfiles or any other auxiliary files required by an application.

To deploy a Docker Compose file:

1. Go to Docker > Stacks > Add Stack.
2. Provide a unique project name for your stack and then select one of the following deployment methods for your Docker Compose file:
   • Editor: Use the integrated text editor to define or paste the content of your Compose file directly into Plesk.
   • Upload: Browse and upload a Compose file from your local computer's storage.
   • Webspace: If your Compose file is already stored on your server, select this option. You will then need to choose the specific domain where the file is located and browse to the Compose file's path.

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

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

Deploying Portainer Containers in Docker

Portainer is an intuitive and powerful open-source container management software that simplifies the deployment, management, and monitoring of Docker environments. It provides a user-friendly graphical interface (GUI) to perform various Docker-related tasks, such as deploying containers and stacks, viewing container status and logs, managing users and teams, and securing your container environments.

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

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

For comprehensive documentation and further details on how to effectively utilize Portainer, please visit the official Portainer documentation.