[Open Source] docker-tar: A small tool for directly downloading Docker tar images from DockerHub

Introduction#

docker-tar is a tool for pulling images from Docker repositories and automatically packaging them into Tar files.
Github: docker-tar

Features#

No Docker environment required: All functionalities are included in the binary, ready to use out of the box.
Multi-Operating System support: Provides relevant binaries that can be used on Linux, Windows, MacOS, Solaris, OpenBSD, and more. See Release for additional supported operating systems.
Multi-Processor Architecture support: Provides relevant binaries that support amd64/x64, i386/x86, arm, arm64, mips, ppc64, and other processor architectures. You can run this tool on a PC or even a router. See Release for more supported architectures.
Image mode download: The tar file downloaded from the image site does not require tagging and can maintain consistency with the input image name.
Login download: Supports Docker repositories and image sites that require authentication.
Select image architecture: Supports selecting Docker images with multiple architectures for download.
Closer to Docker CLI download results: The tar image files downloaded by this tool are identical to those saved using docker pull and docker save.
Lab mode: Provides a lab mode to resolve DNS pollution and SNI blocking, helping you connect directly to certain inaccessible Docker repository sites.

Command Line Usage Instructions#

-action action
        pull: Pull the image tar file.
        list: List the processor architecture images that can be pulled.
  -arch architecture
        Specify the architecture of the image to pull (default is "amd64").
  -image name
        Information about the image to download.
        Defaults to latest if no version is specified.
        Uses DockerHub's Docker repository by default.
        nginx
        home-assistant/home-assistant:stable
        ghcr.io/home-assistant/home-assistant:stable
  -output filename
        The filename of the output tar image. If this option is not specified, a random filename will be generated.
   -username username
        When the Docker repository/image site requires login, a username must be provided.
  -password password
        When the Docker repository/image site requires login, a password must be provided.
  -mirror string
        Use the image site to download the image.
        This method will not modify the name specified by -image.
  -lab
        Lab mode, when enabled, will use default parameters to avoid DNS pollution and SNI blocking. Usable in both pull and list modes.
        Generally, the default settings are sufficient.
  -dns-servers ip list
        This option takes effect when lab mode is enabled.
        The tool has a built-in list; input will override the built-in list.
        DNS server configuration options must be resolved IP addresses, separated by commas.
  -dns-timeout int
         This option takes effect when lab mode is enabled. 
         Configuration for filtering DNS response timeout. (default value 2s)
  -network network
        This option takes effect when lab mode is enabled.
        ip4: Download images using only IPv4.
        ip6: Download images using only IPv6.
        ip: Download images using both IPv4 and IPv6 (default value "ip").

Usage Examples#

List Supported Architectures for Target Image#

Query the architectures supported by nginx.

docker-tar -action list -image nginx

Output:

Available Architecture:
amd64
armv5
armv7
arm64v8
386
mips64le
ppc64le
s390x

Download Image (Direct Download)#

This method requires configuring the HTTPS_PROXY environment variable.
Download the nginx image for the armv7 architecture.

docker-tar -action pull -image nginx -arch armv7 -output nginx.tar

Output:

Pulling from  nginx:latest
[1/7]3d83c6df5858: Downloading  100% |██████████████████████████████████████████████████| (24/24 MB, 1.9 MB/s)
[2/7]9260be83662e: Downloading  100% |██████████████████████████████████████████████████| (37/37 MB, 2.0 MB/s)
[3/7]3058d76256fc: Downloading  100% |██████████████████████████████████████████████████| (628/628 B, 986 kB/s)
[4/7]7888ef92f48d: Downloading  100% |██████████████████████████████████████████████████| (956/956 B, 994 kB/s)
[5/7]5c27d4148f08: Downloading  100% |██████████████████████████████████████████████████| (404/404 B, 400 kB/s)
[6/7]9c733a7e6553: Downloading  100% |█████████████████████████████████████████████████| (1.2/1.2 kB, 1.5 MB/s)
[7/7]931fb3c7333d: Downloading  100% |█████████████████████████████████████████████████| (1.4/1.4 kB, 2.5 MB/s)
Output File:  nginx.tar

Download Image (Through Image Site)#

Download the nginx image for the armv7 architecture.

docker-tar -action pull -image nginx -arch armv7 -output nginx.tar -mirror docker.xuanyuan.me

Output:

Pulling from  nginx:latest
[1/7]9c733a7e6553: Downloading  100% |█████████████████████████████████████████████████| (1.2/1.2 kB, 1.0 MB/s)
[2/7]931fb3c7333d: Downloading  100% |█████████████████████████████████████████████████| (1.4/1.4 kB, 2.8 MB/s)
[3/7]3d83c6df5858: Downloading  100% |███████████████████████████████████████████████████| (24/24 MB, 3.6 MB/s)
[4/7]9260be83662e: Downloading  100% |███████████████████████████████████████████████████| (37/37 MB, 5.2 MB/s)
[5/7]3058d76256fc: Downloading  100% |███████████████████████████████████████████████████| (628/628 B, 68 kB/s)
[6/7]7888ef92f48d: Downloading  100% |██████████████████████████████████████████████████| (956/956 B, 107 kB/s)
[7/7]5c27d4148f08: Downloading  100% |███████████████████████████████████████████████████| (404/404 B, 35 kB/s)
Output File:  nginx.tar

Download Image (Using Lab Mode for Direct Download)#

Download the nginx image for the armv7 architecture.

docker-tar -action pull -image nginx -arch armv7 -output nginx.tar -lab

Output:

Pulling from  nginx:latest
[1/7]3d83c6df5858: Downloading  100% |███████████████████████████████████████████████████| (24/24 MB, 6.9 MB/s)
[2/7]9260be83662e: Downloading  100% |████████████████████████████████████████████████████| (37/37 MB, 12 MB/s)
[3/7]3058d76256fc: Downloading  100% |██████████████████████████████████████████████████| (628/628 B, 489 kB/s)
[4/7]7888ef92f48d: Downloading  100% |██████████████████████████████████████████████████| (956/956 B, 671 kB/s)
[5/7]5c27d4148f08: Downloading  100% |██████████████████████████████████████████████████| (404/404 B, 353 kB/s)
[6/7]9c733a7e6553: Downloading  100% |█████████████████████████████████████████████████| (1.2/1.2 kB, 1.1 MB/s)
[7/7]931fb3c7333d: Downloading  100% |█████████████████████████████████████████████████| (1.4/1.4 kB, 2.8 MB/s)
Output File:  nginx.tar

TODO#

Multi-layer concurrent downloads
Support for chunked downloads, implementing chunked downloads for responses that support Range
Compatibility with Docker API (ContentType)
Code structure and naming adjustments
More user-friendly error output

Compatibility Status (Currently Tested)#

DockerHub
DockerHub image sites
ghcr.io
ghcr.io image sites
quay.io (currently not adapted for application/vnd.docker.distribution.manifest.v1+prettyjws)
quay.io image sites (currently not adapted for application/vnd.docker.distribution.manifest.v1+prettyjws)

Some Possibly Useful Information#

Request Phase	Supported ContentType	Other
Get Token	Only processes response body, ignores type	Access Token, username and password (if needed): Basic
Get all architecture image manifest index	application/vnd.oci.image.index.v1+json	Response of a different type will terminate directly
Get specified architecture image manifest	application/vnd.oci.image.manifest.v1+json	Compatible types are also acceptable
Get image configuration	application/vnd.oci.image.config.v1+json	Compatible types are also acceptable
Download Layer	application/vnd.oci.image.layer.v1.tar application/vnd.oci.image.layer.v1.tar+gzip application/vnd.oci.image.layer.v1.tar+zstd application/vnd.oci.image.layer.nondistributable.v1.tar application/vnd.oci.image.layer.nondistributable.v1.tar+gzip application/vnd.oci.image.layer.nondistributable.v1.tar+zstd application/vnd.docker.image.rootfs.diff.tar application/vnd.docker.image.rootfs.diff.tar.gzip application/vnd.docker.image.rootfs.diff.tar.zstd	Encrypted images are not supported