Module: DOCKER

• 1: Usage
• 2: Parameters
• 3: Playbooks
• 4: Metrics
• 5: FAQ

1 - Usage

Pigsty has built-in Docker support, which you can use to quickly deploy containerized applications.

Getting Started

Docker is an optional module. In Pigsty, whether Docker is installed is controlled by docker_enabled, which is disabled by default.

The docker-ce upstream repository belongs to the infra module. If you need to explicitly include Docker packages in the offline repository, use repo_extra_packages with the docker package alias (mapped to docker-ce and docker-compose-plugin).

repo_modules: infra,node,pgsql     # <--- Keep infra module (Docker upstream belongs to infra)
repo_extra_packages:
  - pgsql-main
  - docker                         # <--- Download Docker (docker-ce + docker-compose-plugin)

After Docker is downloaded, you need to set the docker_enabled: true flag on the nodes where you want to install Docker, and configure other parameters as needed.

infra:
  hosts:
    10.10.10.10: { infra_seq: 1 ,nodename: infra-1 }
    10.10.10.11: { infra_seq: 2 ,nodename: infra-2 }
  vars:
    docker_enabled: true  # Install Docker on this group!

Finally, you can use the docker.yml playbook to install it on the nodes:

./docker.yml -l infra    # Install Docker on the infra group

Installation

If you want to temporarily install Docker directly from the internet on certain nodes, you can use the following command:

./node.yml -e '{"node_repo_modules":"node,infra","node_packages":["docker-ce","docker-compose-plugin"]}' -t node_repo,node_pkg -l <select_group_ip>

This command will first enable the upstream software sources for the node,infra modules on the target nodes, then install the docker-ce and docker-compose-plugin packages (same package names on EL/Debian).

If you want Docker-related packages to be automatically downloaded during Pigsty initialization, refer to the instructions below.

Removal

Because it’s so simple, Pigsty doesn’t provide an uninstall playbook for the Docker module. You can directly remove Docker using an Ansible command:

ansible <selector> -m package -b -a 'name=docker-ce,docker-compose-plugin state=absent'  # Remove docker

Download

To download Docker during Pigsty installation, confirm that repo_modules includes infra (the module containing Docker upstream repositories), then specify Docker packages in repo_packages or repo_extra_packages.

repo_modules: infra,node,pgsql         # <--- Docker upstream repo belongs to infra
repo_packages:
  - node-bootstrap, infra-package, infra-addons, node-package1, node-package2, pgsql-common, docker
repo_extra_packages:
  - pgsql-main
  - docker  # <--- Can also be specified here

The docker specified here (which actually corresponds to the docker-ce and docker-compose-plugin packages) will be automatically downloaded to the local repository during the default deploy.yml process. After downloading, the Docker packages will be available to all nodes via the local repository.

If you’ve already completed Pigsty installation and the local repository is initialized, you can run ./infra.yml -t repo_build after modifying the configuration to re-download and rebuild the offline repository.

Installing Docker requires the Docker YUM/APT repository. In the v4.x default repo_upstream, this repository belongs to the infra module and is usually available out of the box.

Repository

Downloading Docker requires upstream internet software repositories, which are defined in the default repo_upstream with module name infra:

- { name: docker-ce ,description: 'Docker CE' ,module: infra  ,releases: [8,9,10] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.docker.com/linux/centos/$releasever/$basearch/stable'    ,china: 'https://mirrors.aliyun.com/docker-ce/linux/centos/$releasever/$basearch/stable'  ,europe: 'https://mirrors.xtom.de/docker-ce/linux/centos/$releasever/$basearch/stable' }}
- { name: docker-ce ,description: 'Docker'    ,module: infra  ,releases: [11,12,13,22,24,26] ,arch: [x86_64, aarch64] ,baseurl: { default: 'https://download.docker.com/linux/${distro_name} ${distro_codename} stable' ,china: 'https://mirrors.aliyun.com/docker-ce/linux/${distro_name} ${distro_codename} stable' }}

You can reference this repository using the infra module name in repo_modules and node_repo_modules.

Proxy

If your network environment requires a proxy server to access the internet, you can configure the proxy_env parameter in Pigsty’s configuration inventory. This parameter will be written to the proxy related configuration in Docker’s configuration file.

proxy_env:
  no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.aliyuncs.com,mirrors.tuna.tsinghua.edu.cn,mirrors.zju.edu.cn"
  #http_proxy: 'http://username:[email protected]'
  #https_proxy: 'http://username:[email protected]'
  #all_proxy: 'http://username:[email protected]'

When running configure with the -x parameter, the proxy server configuration from your current environment will be automatically generated into Pigsty’s configuration file under proxy_env.

In addition to using a proxy server, you can also configure Docker Registry Mirrors to bypass blocks.

Registry Mirrors

You can use the docker_registry_mirrors parameter to specify Docker Registry Mirrors:

For users outside the firewall, in addition to the official DockerHub site, you can also consider using the quay.io mirror site. If your internal network environment already has mature image infrastructure, you can use your internal Docker registry mirrors to avoid being affected by external mirror sites and improve download speeds.

Users of public cloud providers can consider using free internal Docker mirrors. For example, if you’re using Alibaba Cloud, you can use Alibaba Cloud’s internal Docker mirror site (requires login):

["https://registry.cn-hangzhou.aliyuncs.com"]   # Alibaba Cloud mirror, requires explicit login

If you’re using Tencent Cloud, you can use Tencent Cloud’s internal Docker mirror site (requires internal network):

["https://ccr.ccs.tencentyun.com"]   # Tencent Cloud mirror, internal network only

Additionally, you can use CF-Workers-docker.io to quickly set up your own Docker image proxy. You can also consider using free Docker proxy mirrors (use at your own risk!)

Pulling Images

The docker_image and docker_image_cache parameters can be used to directly specify a list of images to pull during Docker installation.

Using this feature, Docker will come with the specified images after installation (provided they can be successfully pulled; this task will be automatically ignored and skipped on failure).

For example, you can specify images to pull in the configuration inventory:

infra:
  hosts:
    10.10.10.10: { infra_seq: 1 }
  vars:
    docker_enabled: true  # Install Docker on this group!
    docker_image:
      - redis:latest      # Pull the latest Redis image

Another way to preload images is to use locally save d tgz archives: if you’ve previously exported Docker images using docker save xxx | gzip -c > /tmp/docker/xxx.tgz. These exported image files can be automatically loaded via the glob specified by the docker_image_cache parameter. The default location is: /tmp/docker/*.tgz.

This means you can place images in the /tmp/docker directory beforehand, and after running docker.yml to install Docker, these image packages will be automatically loaded.

For example, in the self-hosted Supabase tutorial, this technique is used. Before spinning up Supabase and installing Docker, the *.tgz image archives from the local /tmp/supabase directory are copied to the target node’s /tmp/docker directory.

- name: copy local docker images
  copy: src="{{ item }}" dest="/tmp/docker/"
  with_fileglob: "{{ supa_images }}"
  vars: # you can override this with -e cli args
    supa_images: /tmp/supabase/*.tgz

Applications

Pigsty provides a series of ready-to-use, Docker Compose-based software templates, which you can use to spin up business software that uses external Pigsty-managed database clusters.

2 - Parameters

The DOCKER module provides 8 configuration parameters.

Parameter Overview

The DOCKER parameter group is used for Docker container engine deployment and configuration, including enable switch, data directory, storage driver, registry mirrors, and monitoring.

You can use the docker.yml playbook to install and enable Docker on nodes.

Default parameters are defined in roles/docker/defaults/main.yml

docker_enabled: false             # Enable Docker on current node?
docker_data: /data/docker         # Docker data directory, /data/docker by default
docker_storage_driver: overlay2   # Docker storage driver, overlay2/zfs/btrfs...
docker_cgroups_driver: systemd    # Docker cgroup driver: cgroupfs or systemd
docker_registry_mirrors: []       # Docker registry mirror list
docker_exporter_port: 9323        # Docker metrics exporter port, 9323 by default
docker_image: []                  # Docker images to pull after startup
docker_image_cache: /tmp/docker/*.tgz # Docker image cache tarball glob pattern

docker_enabled

Parameter: docker_enabled, Type: bool, Level: G/C/I

Enable Docker on current node? Default: false, meaning Docker is not enabled.

docker_data

Parameter: docker_data, Type: path, Level: G/C/I

Docker data directory, default is /data/docker.

This directory stores Docker images, containers, volumes, and other data. If you have a dedicated data disk, it’s recommended to point this directory to that disk’s mount point.

docker_storage_driver

Parameter: docker_storage_driver, Type: enum, Level: G/C/I

Docker storage driver, default is overlay2.

See official documentation: https://docs.docker.com/engine/storage/drivers/select-storage-driver/

Available storage drivers include:

• overlay2: Recommended default driver, suitable for most scenarios
• fuse-overlayfs: For rootless container scenarios
• btrfs: When using Btrfs filesystem
• zfs: When using ZFS filesystem
• vfs: For testing purposes, not recommended for production

docker_cgroups_driver

Parameter: docker_cgroups_driver, Type: enum, Level: G/C/I

Docker cgroup filesystem driver, can be cgroupfs or systemd, default: systemd

docker_registry_mirrors

Parameter: docker_registry_mirrors, Type: string[], Level: G/C/I

Docker registry mirror list, default: [] empty array.

You can use Docker mirror sites to accelerate image pulls. Here are some examples:

docker_registry_mirrors:                        # Choose one or more
  - https://docker.m.daocloud.io                # DaoCloud mirror
  - https://docker.1ms.run                      # 1ms mirror
  - https://mirror.ccs.tencentyun.com           # Tencent Cloud internal mirror
  - https://registry.cn-hangzhou.aliyuncs.com   # Alibaba Cloud mirror (requires login)

You can also consider using a Cloudflare Worker to set up a Docker Proxy for faster access.

If pull speeds are still too slow, consider using alternative registries: docker login quay.io

docker_exporter_port

Parameter: docker_exporter_port, Type: port, Level: G

Docker metrics exporter port, default is 9323.

The Docker daemon exposes Prometheus-format monitoring metrics on this port for collection by monitoring infrastructure.

docker_image

Parameter: docker_image, Type: string[], Level: G/C/I

List of Docker images to pull, default is empty list [].

Docker image names specified here will be automatically pulled during the installation phase.

docker_image_cache

Parameter: docker_image_cache, Type: path, Level: G/C/I

Local Docker image cache tarball glob pattern, default is /tmp/docker/*.tgz.

You can use docker save | gzip to package images and automatically import them during Docker installation via this parameter.

.tgz tarball files matching this pattern will be imported into Docker one by one using:

cat *.tgz | gzip -d -c - | docker load

3 - Playbooks

The Docker module provides a default playbook docker.yml for installing Docker Daemon and Docker Compose.

docker.yml

Playbook source file: docker.yml

Running this playbook will install docker-ce and docker-compose-plugin on target nodes with the docker_enabled: true flag, and enable the dockerd service.

The following are the available task subsets in the docker.yml playbook:

• docker_install : Install Docker and Docker Compose packages on the node
• docker_admin : Add specified users to the Docker admin user group
• docker_dir : Create Docker related directories
• docker_config : Generate Docker daemon service configuration file
• docker_launch : Start the Docker daemon service
• docker_register : Register Docker daemon as a monitoring target (alias tags: register / add_metrics)
• docker_image : Attempt to load pre-cached image tarballs from /tmp/docker/*.tgz (if they exist)

The Docker module does not provide a dedicated uninstall playbook. If you need to uninstall Docker, you can manually stop Docker and then remove it:

systemctl stop docker                        # Stop Docker daemon service
yum remove docker-ce docker-compose-plugin   # Uninstall Docker on EL systems
apt remove docker-ce docker-compose-plugin   # Uninstall Docker on Debian systems

Changing docker_enabled to false only makes docker.yml skip the entire Docker role. It does not stop or uninstall an existing Docker deployment, nor delete /data/docker. The manual commands above also leave the data directory in place. Docker’s VictoriaMetrics file-discovery target can be deregistered together with the node through the node_deregister task in node-rm.yml.

4 - Metrics

This snapshot records 123 monitoring metric families for the DOCKER module. The metrics present at runtime vary with package version, enabled collectors, and target state.

5 - FAQ

Who Can Run Docker Commands?

By default, Pigsty adds both the management user running the playbook on the remote node (i.e., the SSH login user on the target node) and the admin user specified in the node_admin_username parameter to the Docker operating system group. All users in this group (docker) can manage Docker using the docker CLI command.

If you want other users to be able to run Docker commands, add that OS user to the docker group:

usermod -aG docker <username>

Working Through a Proxy

During Docker installation, if the proxy_env parameter exists, the HTTP proxy server configuration will be written to the /etc/docker/daemon.json configuration file.

Docker will use this proxy server when pulling images from upstream registries.

Tip: Running configure with the -x flag will write the proxy server configuration from your current environment into proxy_env.

Using Mirror Registries

If DockerHub access is slow in mainland China network environments, you can prioritize:

• Configure available mirrors with docker_registry_mirrors
• Or configure proxy_env to pull via proxy
• Or directly use other public registries (such as quay.io)

For example:

docker login quay.io    # Enter username and password to log in

Adding Docker to Monitoring

During Docker module installation, you can register Docker as a monitoring target by running the docker_register subtask (or alias tag add_metrics) for specific nodes:

./docker.yml -l <your-node-selector> -t docker_register

Using Software Templates

Pigsty provides a collection of software templates that can be launched using Docker Compose, ready to use out of the box.

But you need to install the Docker module first.