Module: DOCKER

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

1 - Usage

Pigsty includes Docker support. Use it to deploy containerized applications quickly.

Getting Started

Docker is an optional module. The docker_enabled parameter controls Docker installation. It is disabled by default.

The docker-ce upstream repository belongs to the infra module. To include Docker packages in the offline repository, set repo_extra_packages to the docker package alias. This alias maps 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 you download Docker, set docker_enabled to true on each target node. Set the 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!

Use the docker.yml playbook to install Docker on these nodes:

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

Installation

To install Docker directly from the internet on selected nodes for a temporary need, use this 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 first enables the upstream software sources for the node,infra modules on the target nodes. Then it installs docker-ce and docker-compose-plugin. These package names are the same on EL and Debian.

To download Docker packages automatically during Pigsty initialization, use the instructions below.

Removal

The Docker module does not include an uninstall playbook. To remove Docker directly, use this 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, make sure that repo_modules includes infra. This module contains the Docker upstream repositories.

Specify the 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 default deploy.yml process downloads the docker package alias to the local repository. This alias contains docker-ce and docker-compose-plugin. After the download, all nodes can get these packages from the local repository.

If Pigsty installation and local repository initialization are complete, change the configuration first. Then run ./infra.yml -t repo_build to download the packages again and rebuild the offline repository.

Docker installation requires the Docker YUM/APT repository. In the v4.x default repo_upstream, this repository belongs to the infra module. It is usually available without extra configuration.

Repository

Docker downloads require upstream internet software repositories. The default repo_upstream defines these repositories under the infra module:

- { 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' }}

To select this repository, use infra in repo_modules and node_repo_modules.

Docker’s official software repository is blocked by default in mainland China. Use mirror sites in China to download the packages.

If Docker downloads fail in mainland China, check region in your configuration inventory. If it is default, the automatically configured region: china can resolve the problem.

Proxy

If internet access requires a proxy server, set proxy_env in the Pigsty configuration inventory. Pigsty writes this value to the proxy configuration in the Docker 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 you run configure with -x, Pigsty reads the proxy settings from your current environment. It writes these settings under proxy_env in the Pigsty configuration file.

You can also configure Docker Registry Mirrors to bypass network blocks.

Registry Mirrors

Use docker_registry_mirrors to specify Docker Registry Mirrors.

Outside the firewall, you can consider quay.io as an alternative to the official DockerHub site. If your internal network has established image infrastructure, use its Docker registry mirrors. Internal mirrors reduce dependence on external sites and improve download speeds.

Public cloud providers can offer free internal Docker mirrors. For example, Alibaba Cloud provides an internal Docker mirror site that requires login:

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

Tencent Cloud provides an internal Docker mirror site that requires access from its internal network:

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

You can use CF-Workers-docker.io to set up your own Docker image proxy quickly. You can also consider free Docker proxy mirrors. Use these public mirrors at your own risk.

Pulling Images

Use docker_image and docker_image_cache to specify images to load during Docker installation.

After installation, Docker contains the specified images if the image downloads succeed. If this task fails, the playbook automatically ignores the failure and skips the task.

For example, specify the images 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

You can also preload images from local tgz archives previously exported with save. For example, export an image with docker save xxx | gzip -c > /tmp/docker/xxx.tgz.

The docker_image_cache glob selects the exported image files to load automatically. Its default value is /tmp/docker/*.tgz.

Put these image archives in /tmp/docker before you run docker.yml. The playbook installs Docker and automatically loads the archives.

The self-hosted Supabase tutorial uses this method. Before Docker installation and Supabase startup, copy the *.tgz archives from local /tmp/supabase to /tmp/docker on the target node:

- 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 ready-to-use software templates based on Docker Compose. Use these templates to start business software that connects to external database clusters managed by Pigsty.

2 - Parameters

The DOCKER module provides 8 configuration parameters.

Parameter Overview

Use the DOCKER parameter group to deploy and configure the Docker container engine. It controls the 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

Specifies whether to enable Docker on the current node. The default is false, which disables Docker.

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, we recommend its mount point for this directory.

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. Set it to cgroupfs or systemd. The default is 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 [].

During installation, Docker automatically pulls the images specified here.

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.

Use docker save | gzip to package images. Set this parameter to import those images automatically during Docker installation.

Docker imports each .tgz tarball that matches this pattern with the following command:

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

3 - Playbooks

The Docker module provides the docker.yml playbook to install Docker Daemon and Docker Compose.

docker.yml

Playbook source file: docker.yml

The playbook installs docker-ce and docker-compose-plugin on target nodes that have docker_enabled: true. It also enables the dockerd service.

The docker.yml playbook has these task subsets:

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

The Docker module does not provide a dedicated uninstall playbook. To uninstall Docker, manually stop it and 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

If you set docker_enabled to false, docker.yml skips the entire Docker role. This change does not stop or uninstall an existing Docker deployment. It does not delete /data/docker.

The manual commands above also preserve the data directory. To deregister Docker’s VictoriaMetrics file-discovery target with the node, run 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 two users to the Docker operating system group. One is the management user that runs the playbook: the SSH login user on the target node. The other is the admin user specified by node_admin_username. All users in this group (docker) can manage Docker using the docker CLI command.

To let another user run Docker commands, add that OS user to the docker group:

usermod -aG docker <username>

Working Through a Proxy

During Docker installation, Pigsty checks for proxy_env. If this parameter exists, Pigsty writes the HTTP proxy configuration to /etc/docker/daemon.json.

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

Tip: Run configure with -x to copy the proxy settings 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 installation, run the docker_register subtask for the target nodes to register Docker for monitoring. You can also use its alias tag, add_metrics:

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

Using Software Templates

Pigsty provides ready-to-use software templates for Docker Compose. Install the Docker module before you start these templates.