Skip to main content
Version: v1.9

Hangar Tutorial

Getting Started​

Follow this instruction to setup a demo distribution registry server and use Hangar to copy images.

  1. Setup a demo registry server.

    docker run -d -p 5000:5000 --restart=always --name registry registry:2

  2. Run Hangar inside the container image:

    docker run -it -v $(pwd):/hangar --network=host cnrancher/hangar:latest

  3. Create an image list file for copy images from the Docker Hub to the demo registry server:

    example_image_list.txt
    cnrancher/hangar:latest
    cnrancher/hangar:v1.9.0

    Use Hangar mirror command to copy images from Docker Hub to the demo registry server:

    hangar mirror \
        -f 'example_image_list.txt' \
        -s 'docker.io' \
        -d '127.0.0.1:5000' \
        --arch amd64,arm64 \
        --os linux \
        --tls-verify=false
    note

    By default, the registry server can be login with any username and password.

    You can configure the authentication config of the registry server by refer to Distribution Registry Token Authentication.

  4. Use the hangar inspect command to inspect the copied image manifest index:

    hangar inspect docker://127.0.0.1:5000/cnrancher/hangar:latest --raw --tls-verify=false
    {
      "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
      "schemaVersion": 2,
      "manifests": [
        {
        "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    ......

Best Practice​

You can refer to the Installation Guide to install hangar on your system.

For more detailed usage example of hangar to setup a private image registry server with Kubernetes clusters, see Hangar Best Practice.

Configuration​

The configuration file of hangar is compatible with the containers/image configuration files.

  • /etc/containers/policy.json:

    The default trust policy file, use --insecure-policy option to skip policy check.

    The default policy file can be obtained at default-policy.json.

  • /etc/containers/registries.d/default.yaml:

    The default registries configuration file.

Commands​

  • mirror: Mirror container images between image registries.
  • save: Save container images from registry server into archive file.
  • load: Load container images from archive file to registry server.
  • sync: Sync (append) extra images into archive file.
  • sign: Sign container images with sigstore key-pair.
  • scan: Scan container image vulnerabilities.
  • view: View container image SBOM/Provenance data.
  • archive: Operations for the Hangar archive file.
  • generate-list: Generate image list file for Rancher. Hanagr also provides some extra commands for advanced usage, see advanced usage.

Supported Registries​

Hangar can work with API V2 container image registries:

You need to ensure that the registry supports following mediaTypes:

  • application/vnd.docker.distribution.manifest.list.v2+json
  • application/vnd.oci.image.index.v1+json
note

Harbor 1.X does not support these mediaTypes, you need to upgrade to Harbor 2.X to use hangar.

Q&A​

For frequently asked questions, see Q&A.