Using Docker for Application Deployment

Docker is a powerful platform designed for running applications within isolated environments called containers. It provides the flexibility to utilize specific software, such as Redis or MongoDB, or particular versions of software that might not be natively supported by your operating system or require complex compilation processes.

Integrated as an extension, Docker allows users to effortlessly run and manage containers based on various Docker images. This functionality extends to using Docker both on the local host and on remote servers, providing versatile deployment options.

This article will guide you through the process of creating, configuring, and managing Docker containers within a unified control panel. You will also learn how to effectively control remote Docker hosts from this interface.

Requirements and Considerations

Warning: The Docker extension directly downloads images from public repositories without any pre-configuration. Some Docker containers or the software within them are intended for trusted environments only and may necessitate additional security setup. Before deploying these downloaded images, it is crucial to enhance their security independently. For specific instructions, refer to the documentation provided by the container or software vendor. For example, consult the security section in the Redis documentation.

• Docker is supported on the control panel 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, and Rocky Linux 8.x.
• For Windows-based control panel installations, you can leverage Docker installed on a remote machine (refer to the "Using Remote Docker" section later in this guide).
• Docker cannot be utilized within a control panel installation that is itself deployed in a Docker container.
• Docker operations are exclusively supported on x64 systems.
• Docker containers managed through the control panel cannot be directly migrated or backed up. However, data used by these containers can be backed up (see "Volume Mapping" below), or snapshots can be downloaded.
• When using specific virtualization platforms, newly created CentOS 7-based containers may have the firewall enabled by default for enhanced security. The platform administrator must manually configure the firewall to ensure that all necessary ports for the control panel's operation are open.

Prerequisites

Before you can begin utilizing Docker functionalities, the Docker extension must be installed on your server:

• If you are the platform administrator, install the extension from the Extensions Catalog.
• Otherwise, please contact your hosting provider and request them to install the extension on your behalf.

Once the extension is successfully installed, you will find the Docker option readily available in the navigation pane, indicating that you are ready to proceed.

Container Management

You can access a vast catalog of images from public image repositories within the Run Container catalog (Docker > Containers > Run Container).

To access the catalog:

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

To find available images, simply use the search box. You can specify the image name, the repository, or both.

The following repositories are typically available for search:

• Local repository - This contains images that have already been downloaded and are stored on your server. For more details, refer to the "Managing Local Images" section later in this guide.
• Public image repositories (e.g., Docker Hub).

Many applications offer multiple versions. You can run a specific version by selecting the appropriate tag, as demonstrated below:

To run a new container:

1. Go to Docker > Containers > Run Container.
2. Use the search box to locate images in the catalog. If an image is stored locally, (local) will appear next to its version.
3. To view detailed image descriptions and documentation on public image repositories, click the more info icon. This option is not applicable to local images.
4. Click the desired image card.

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

   The system will create a container and prompt you to specify its settings, such as environment variables, before initiating its run. You have the option to cancel this process by clicking Cancel on the Settings screen. For comprehensive details about these settings, please refer to the "Container Settings" section below.

5. After adjusting the settings as needed, click Run. The newly created container will then appear in the list within the Containers tab.

Review the Console Log to verify that the container is running without any issues.

Container Settings

Note: You do not need to stop a container to change its settings. When you save new configurations, the platform efficiently recreates the container with the updated parameters.

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

Limiting Memory

By default, RAM usage in a Docker container is unlimited. To enforce a memory limit, select the Memory limit checkbox and enter the desired limit value in megabytes (MB) in the corresponding field.

Note: Currently, CPU and Disk usage cannot be limited for Docker containers. Docker containers are treated as administrator-level objects and are not governed by subscription-level cgroup limits (CPU, RAM, Disk usage).

Automatic Start

If the option Automatic start after system reboot is not selected, websites relying on this container might become unavailable after a system reboot, requiring you 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 port on the host system, deselect Automatic port mapping and specify a different external port under Manual mapping. If Manual mapping does not appear after deselection, it indicates that the container does not expose any ports.

When using manual mapping, Docker typically binds only to the specified port on the host system’s localhost interface (127.0.0.1). This approach 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 on 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 (e.g., MySQL/MariaDB typically requires authentication, while Redis might not by default). Making an application within a container accessible from the internet without proper authentication can expose it to malicious attacks.

Volume Mapping

Docker volumes are persistent directories on your server that are mounted to a Docker container. This mechanism ensures that data remains accessible from your host system and is not deleted when you stop or remove a container.

Warning: Data stored in Docker volumes will not be included in the platform's standard backup. To prevent data loss, it is recommended to back up any essential data stored in a volume using a third-party backup tool.

For more detailed information regarding data management in containers, please refer to the official Docker documentation.

To establish a volume mapping, specify the following:

• In the Host field: The absolute path to the directory on the server that you intend to mount within the container.
• In the Container field: The absolute path to a directory inside the container.

To map additional directories, click Add one more.

Setting Environment Variables

Environment variables are crucial for the application running inside a container. You may need to add new variables or modify existing ones to suit your application's requirements. The control panel allows you to add as many variables as necessary.

Operations with Containers

You can perform a variety of operations to manage your containers efficiently:

• Stop (Stop), start (Start), or restart (Restart) a container. In these instances, the container will be recreated using its current settings.

  Note: If data was not saved to mounted volumes (refer to the "Volume Mapping" section), it will be lost upon recreation.

• Click the arrow next to the container name to view its logs and monitor resource consumption.
• Click the settings icon next to the container to modify its settings, such as environment variables or volume mapping (Settings).
• Rename a container via Settings > Container name.

Click the more options icon next to the container to access additional actions:

• Recreate a container using the same image version or a different one (Recreate).
• Create a new image based on your customized container settings (Save as Image).
• Download a snapshot of the container's current state (Download Snapshot).
• Remove a container entirely (Remove).

Recreating a Container

Recreating a container is typically necessary when you wish to update the application to a newer version. However, you can rebuild a container using any application version available in the catalog, not just newer ones.

Custom settings are preserved during the recreation process. To ensure data persistence for the application inside a container, it is essential to define volume mapping before recreating the container. Volume mapping provides access to directories used within a container (see "Volume Mapping" in container settings for more details).

To recreate a container:

1. Go to Docker and click the more options icon next to the container you intend 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 Services

By default, the platform utilizes a locally installed Docker service. However, you have the option to employ one or more Docker services installed on external machines. It's important to note that only one remote service can be active at any given time. The currently active server is displayed in the Environments tab of the Docker settings page.

Note: Managing remote Docker services may require an additional add-on for your control panel license. Without this add-on, you are typically limited to managing only the local Docker service running on the server.

Configuring Remote Services

To integrate a remote server running Docker, configure it as described in the official Docker documentation to enable its use as a remote server within the control panel.

Managing Remote Services

You can establish a secure connection between your control panel server (with the Docker extension installed) and a remote node hosting a Docker service.

The following steps are applicable across various operating systems:

These 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 .pem files. You can use the following example. Replace the IP on line 4 with the IP address of your remote node and run each command:

   openssl genrsa -aes256 -out ca-key.pem 4096
   openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
   openssl genrsa -out server-key.pem 4096
   openssl req -subj "/CN=192.0.2.1" -new -key server-key.pem -out server.csr
   openssl x509 -req -days 365 -sha256 -in 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 host 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 on your local machine for the client to establish a remote connection:

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

On the local server, configure the Docker remote host:

1. Go to Docker > Environments.
2. Click Add Server and specify the settings for the remote server hosting Docker.
3. To begin using this Docker service within the control panel, ensure Set active is selected.

The link to Docker will then appear in the navigation pane.

To switch between different Docker services:

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

Alternatively, you can activate the Docker node while editing its settings.

Creating Images with Custom Settings

If you need to create a new image based on modifications made to an existing container, use the Save as Image command. This action captures a snapshot of your container, which then appears as a new image in your image catalog. This method is ideal for creating images with specific custom settings, such as environment variables.

To create an image from one of your containers:

Go to Docker > Containers, click the more options icon next to the container, and then click > Save as Image. In the Save <container name> as Image side panel, specify:

• Image name.
• An optional Tag. This allows you to specify the image version. By default, the version will be “latest”.

The newly created image will appear in the Images tab and will be marked as Local image.

Managing Local Images

Local images are Docker images stored on your local disk, eliminating the need to download them from online repositories each time they are used.

An image becomes local under several circumstances:

• You have selected any version (tag) of an image, and the download process has begun. Even if you subsequently run a container or cancel the operation (on the Settings screen), the image is saved locally.
• You upload an image to Docker within the control panel interface (using Upload image in the Docker Images tab).
• You have created a custom image from an existing container (refer to "Creating Images with Custom Settings" for more information).
• You have built an image directly using the command-line interface.

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

If at least one downloaded version from a group of versions belonging to an image exists, this image will be labeled Local image in the catalog. The control panel also indicates how many local images are available for a particular product.

To view and remove outdated local images:

1. Go to Docker > Images.
2. Use the Search bar to locate a specific local image.
3. To view all local images of a particular product, click the link beneath the product name. This will display all local images’ tags and the disk space they occupy.
4. Select the specific image(s) you wish to remove and click Remove.

Configuring Nginx to Proxy Requests from Domains to a Container

Some Docker containers expose ports to make the applications within them accessible. When integrating an application running in a Docker container with your website, it can be inconvenient to require users to specify a non-standard port in the URL. To enhance user experience, you can configure Nginx to proxy requests from your domains to that specific container port, allowing domains to use a standard port (e.g., 80) without explicit port specification in the URL.

Requirements

• Nginx must be running on your server.
• 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 wish to configure.
2. Turn off Automatic port mapping.
3. Manually map the port inside the container to a specific port on your system (for instance, 32768). You can choose to make this host port inaccessible from the Internet for added security.

After mapping, you can set up Nginx to proxy requests from your domains to this host port, allowing your domains to utilize a standard Nginx port (e.g., 80). To enable this, add a rule for Nginx in the domain settings.

To add a rule for Nginx in the domain settings:

Go to Websites & Domains > the domain > Docker Proxy Rules > Add Rule and specify the following:

• URL: Specify the URL of the website that uses an application running in a container. This can be the main website or a specific section of it.
• Container: Select the application running as a Docker container.
• Port: Choose one of the port mappings that was defined in the container settings (a port inside the container mapped to a port on your system). Nginx will then proxy requests to this specified port on the system.

Proxy rules are implemented in the web server configuration, for example, in the website’s nginx.conf file (typically found 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

These proxy rules are designed to function effectively even on servers situated behind NAT.

Note: Docker containers connected via Proxy Rules to a website do not contribute to the subscription’s disk space usage. An exception 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 website’s disk space usage.

Deploying Docker Compose YAML Files

You have the capability to deploy Docker Compose YAML files using an online text editor, by uploading a file from your local storage, or by selecting a Docker Compose file already stored within a website’s home directory. Standard operations on stacks are fully supported, including up (which encompasses pull and force-recreate), stop, and down. You can also modify and update these stacks after their initial creation.

Note: This section does not support deploying 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 project name and select one of the following methods for deploying your Docker Compose file:

   • Editor: Define or paste the content of your Compose file directly into the editor.
   • Upload: Upload a Compose file from your local storage.
   • Webspace: Select a Compose file that is already stored in a domain’s home directory. For this option, choose the domain where the file is located and then browse to the Compose file’s exact location.

You can also declare and build custom containers. Any artifacts generated during the build process will be placed within the website’s home directory.

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

Deploying Portainer Containers in Docker

Portainer is a comprehensive container management software that streamlines the deployment of containers and stacks, provides insights into container status and logs, facilitates user and team creation, and enhances environment security, among other features.

To install Portainer, navigate to Docker > Install Portainer. Once the installation is complete, to manage your Portainer containers within Docker, go to Docker > Go to Portainer.

Note: Portainer is currently offered as a beta feature.

For additional information regarding Portainer, consult the official Portainer documentation.