Using Docker with Plesk Obsidian

Docker is a powerful platform designed for running applications within isolated environments called containers. It offers a flexible solution for utilizing specific software, such as Redis or MongoDB, or particular software versions that might not be natively supported by your operating system or may require custom compilation.

Integrated as a Plesk extension, Docker enables users to effortlessly run and manage containers based on a wide array of Docker images. This functionality extends to both local host environments and remote servers, providing versatile deployment options.

This comprehensive guide will walk you through the process of creating, configuring, and managing Docker containers directly within Plesk. Additionally, you will discover how to control and interact with remote Docker hosts from your Plesk interface, ensuring seamless integration and management.

Requirements and Limitations

Warning: The Docker extension downloads images from Docker Hub without any pre-configuration. Some Docker containers or the software they contain are intended for trusted environments only and may necessitate additional security measures. Before launching these downloaded images within Plesk, it is crucial to enhance their security independently. For detailed instructions, please consult the documentation provided by the container or software vendor. As an example, refer to the security section in the Redis documentation.

• Docker is officially supported in Plesk for the following operating systems: CentOS 7, Red Hat Enterprise Linux 7, Debian 10, Debian 11, Debian 12, Ubuntu 18.04, Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, AlmaLinux 8.x, AlmaLinux 9.x, Rocky Linux 8.x, and Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later.
• For Plesk on Windows installations, Docker can be utilized when installed on a remote machine. Refer to the section "Using Remote Docker" later in this guide for further details.
• It is not possible to use Docker within a Plesk instance that is itself deployed in a Docker container.
• Accessing remote Docker services in Plesk requires an additional license. This can be acquired separately or as part of the Hosting Pack, Power Pack, or Developer Pack.
• Docker exclusively operates on x64 systems.
• Docker containers managed within Plesk cannot be migrated or backed up directly. However, it is possible to back up the data utilized by containers (see "Volume Mapping" below) or download snapshots.
• Virtuozzo 7 with Update 1 Hotfix 1 (7.0.1-686) or later is supported. Note that with this update, new CentOS 7-based containers are created with the firewall enabled by default, reflecting Virtuozzo’s commitment to enhanced security. Plesk administrators must manually configure the firewall to ensure that ports essential for Plesk operations are open.

Prerequisites

Before you can begin leveraging Docker's capabilities, the Docker extension must be installed on your Plesk server:

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

Once the Docker extension is successfully installed, you will find the "Docker" option conveniently located in the Navigation Pane, ready for use.

Containers

You can access a vast catalog of images from Docker Hub within the "Run Container" section of Plesk (Docker > Containers > Run Container).

To access the container catalog:

• If you have not installed any containers previously, navigate to Docker > Containers, and then click Run Container.
• If you have existing containers, 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 contains images that have already been downloaded and are stored on your server running Docker. For more information, 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 run a specific version by selecting the appropriate tag from the available options.

To run a new container:

1. Go to Docker > Containers > Run Container.
2. Use the search box to find your desired images in the catalog. If an image is stored locally, (local) will be displayed next to its version.
3. To view detailed image descriptions and documentation on Docker Hub, click the more info icon . This option is not available for local images.
4. Click on the image card to select it.
   • To run a specific version, choose the desired image version from the Image version drop-down menu and click Next.
   • To deploy the latest version of the chosen application, simply click Next.

   Plesk will then proceed to create a container and prompt you to define its settings, such as environment variables, before initiating its run. You can abort the process at any point by clicking Cancel on the Settings screen. For a comprehensive overview of these settings, please refer to the "Container Settings" section below.

5. After adjusting the settings to your requirements, click Run. The newly launched container will then appear in the list on the Containers tab.

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

Container Settings

Note: You do not need to stop a container to modify its settings. When you save new settings, Plesk automatically recreates the container with the updated configuration.

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

Limiting Memory

By default, Docker containers have no upper limit on RAM usage. To impose a memory restriction, select the Memory limit checkbox and input the desired limit in megabytes in the MB field.

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

Note: Docker containers are considered administrator-level objects and are not governed by subscription-level cgroup limits (which control CPU, RAM, and disk usage).

Automatic Start

If the option Automatic start after system reboot is not selected, any websites relying on this container might become unavailable following a system reboot. In such cases, you would need to manually start the container.

Port Mapping

By default, Automatic port mapping is enabled, which maps the container's internal port to a randomly assigned port on the host system (e.g., 32768).

To customize the host system's port, deselect Automatic port mapping and specify a different external port under Manual mapping. If the Manual mapping option does not appear after deselection, it indicates that the container does not expose any ports.

When employing manual mapping, Docker typically binds only to the specified port on the host system's localhost interface (127.0.0.1) by default. This configuration makes the port inaccessible from the internet, safeguarding the application within the container from external attacks. To allow Docker to bind to the specified port across all network interfaces of the host system, deselect Make the port inaccessible from the Internet. Be aware that doing so will make the application inside the container accessible from the internet via any of the host system’s IP addresses on the specified port.

Warning: Docker 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 does). Exposing an application inside a container to the internet without proper authentication and security measures can make it vulnerable to attacks by malicious actors.

Volume Mapping

Docker volumes are persistent directories on your server that are mounted into a Docker container. This mechanism provides durable storage that remains accessible from your host system. Crucially, data stored in Docker volumes is not deleted when a container is stopped or removed.

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

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

To establish a volume mapping, provide the following details:

• In the Host field, enter the absolute path to the directory on your server that you intend to mount within the container.
• In the Container field, specify the absolute path to a directory inside the container where the host directory will be mounted.

To map additional directories, click Add one more.

Setting Environment Variables

Environment variables are crucial for configuring applications running inside a container. You may need to add new variables or modify existing ones to suit your application's requirements. Plesk allows you to add as many environment variables as necessary.

Operations with Containers

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

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

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

• Click the arrow icon next to a container to view its logs and current resource consumption.
• Click the settings icon next to a container to access and modify its configuration, including environment variables or volume mapping (Settings).
• Rename a container by navigating to its settings (Settings > Container name).

Click the more options icon next to a container to perform additional actions:

• Recreate a container, either using the same image version or a different one available in the catalog (Recreate).
• Create a new image based on your container's current state and custom settings (Save as Image).
• Generate and download a snapshot of a container's current state (Download Snapshot).
• Permanently remove a container from your system (Remove).

Recreating a Container

Recreating a container is typically necessary when you need to update the application to a newer version. However, you have the flexibility to rebuild a container using any available application version from the catalog, not just a more recent one.

During the recreation process, all custom settings are meticulously preserved. To safeguard data utilized by the application within the container, it is essential to configure volume mapping before initiating a container recreation. Volume mapping ensures persistent access to directories used inside a container. (Refer to Volume Mapping in the container settings for details).

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, then specify the desired image version and whether to use default environment variables.

Using Remote Docker

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

Note: Managing remote Docker services requires a Plesk license key add-on. Without this add-on, you are limited to managing the local Docker service running on the Plesk server.

Configuring Remote Services

To use a remote server with Docker in Plesk, you must configure that remote server as described in the official Docker documentation on securing the Docker daemon with HTTPS.

Managing Remote Services

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

These steps must be executed on the **remote host**:

1. Create the `/etc/docker/daemon.json` configuration file for Docker with the following content. This configuration specifies the Docker daemon to listen on both a TCP socket (for remote connections) and a Unix socket (for local connections), while enforcing TLS for secure 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"
}

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

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

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 connection settings for your remote Docker server.
3. To immediately begin using this Docker service within Plesk, ensure that Set active remains selected.

Once configured, the link to the active Docker service will appear in the Navigation Pane.

To seamlessly 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 also set a Docker node as active while in the process of editing its settings.

Creating Images with Custom Settings

If you have made specific modifications to a container and wish to save these changes as a reusable template, you can utilize the Save as Image command. This operation creates a snapshot of your customized container, which then appears as a new, distinct image within your image catalog. This functionality is particularly useful for creating images pre-configured with custom settings, such as environment variables.

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

Navigate to Docker > Containers, click the more options icon next to the relevant container, and then select Save as Image. In the "Save <container name> as Image" side panel, specify the following details:

• Image name: Provide a descriptive name for your new custom image.
• An optional Tag: You can specify a version for the image here. By default, if no tag is provided, the version will be "latest."

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

Managing Local Images

Local images are Docker images that are stored directly on your local disk. This means there is no need to download them from the online Image Catalog when they are needed, as they are readily available on your server.

An image becomes a local image under several circumstances:

• When you select any version (tag) of an image and the download process begins. 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 directly within Plesk using the Upload image option in the Docker Images tab.
• When you create a custom image from an existing container (refer to "Creating Images with Custom Settings" for more information).
• When you build an image using the command-line interface.

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

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

To view and remove outdated local images:

1. Go to Docker > Images.
2. To find a specific local image, utilize the Search bar.
3. To view all local images associated with a particular product, click the link displayed under the product name. This will show all local images' tags and the disk space they occupy.
4. Select the specific image(s) you wish to remove and 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 externally. However, directly specifying a non-standard port in a website's URL can be inconvenient for users.

To mitigate this, you can configure Nginx to act as a proxy, forwarding requests from your domains to the container's exposed port. This enables domains to utilize standard ports (such as 80 or 443) without the need to explicitly mention the container's internal port in the URL, providing a cleaner and more user-friendly experience.

Requirements

• Nginx must be running and active in Plesk.
• 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 configure.
2. Deactivate Automatic port mapping.
3. Manually map the port inside the container to a specific port on your system (for example, 32768). You have the option to make this host port inaccessible from the Internet for enhanced security.

Once the port is mapped, you can set up Nginx to proxy requests. To achieve this, add a proxy rule within the domain settings.

To add a rule for Nginx in the domain settings:

Navigate to Websites & Domains > your domain > Docker Proxy Rules > Add Rule and provide the following information:

• URL: Specify the URL of the website or a specific path that will utilize the application running in the Docker container. This can be the main website or a particular section of it.
• Container: Select the Docker container that hosts the application you want to proxy requests to.
• Port: Choose one of the port mappings that you previously defined in the container settings (a port inside the container mapped to a specific port on your host system). Nginx will then proxy requests to this specified host system port.

These proxy rules are implemented directly within the web server configuration, typically found in the website’s `nginx.conf` file (located 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

Proxy rules are designed to function effectively even on servers deployed behind Network Address Translation (NAT).

Note: Docker containers connected to a website via Proxy Rules are generally not factored into the subscription’s disk space usage. An important exception to this is when a website directory is mounted to a Docker container as a volume; in this specific scenario, all files located within the container will be counted towards the website’s overall disk space usage.

Deploying Docker Compose YAML Files

Plesk facilitates the deployment of Docker Compose YAML files through various convenient methods: you can use an online text editor to define your Compose file, upload a file directly from your local storage, or select a Docker Compose file already stored within a website’s Home directory. Plesk supports common operations on Docker Compose stacks, 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 is specifically for Docker Compose files and does not support the deployment of Dockerfiles or any other application-specific files.

To deploy a Docker Compose file:

1. Go to Docker > Stacks > Add Stack.
2. Fill in a project name for your stack and then choose one of the following methods for deploying your Docker Compose file:
   • Editor: Directly define or paste the content of your Docker Compose file into the provided text editor.
   • Upload: Upload a Docker Compose file from your local storage.
   • Webspace: Select an existing Docker Compose file stored within a domain’s Home directory. If choosing this option, you will need to select the specific domain where the file is located and then browse to the Compose file's path.

You have the flexibility to declare and build custom containers within your Docker Compose setup. Any artifacts generated during this build process will be automatically placed inside the respective website’s Home directory.

For more detailed information regarding the Docker Compose file format and its syntax, please consult the official Docker documentation.

Deploying Portainer Containers in Docker

Portainer is a robust container management software that significantly simplifies the deployment and oversight of containers and stacks. It provides an intuitive interface to monitor container status and logs, manage users and teams, and enhance the security of your Docker environments, among other features.

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

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

For more comprehensive details about Portainer and its capabilities, please refer to the official Portainer documentation.