Quick Start Guide

This guide explains how to set up a local image synchronization pipeline. You will run a local target registry, create authentication and synchronization rules, execute the copy process, and verify that the image was transferred successfully.

Prerequisites

• image-syncer compiled or downloaded (see Installation and Setup).
• Docker installed locally to host the target registry and verify results.

---

Step 1: Start a Target Local Registry

For testing purposes, spin up an insecure local Docker registry container. This registry will listen on port 5000:

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

To check if the registry is active, run a simple HTTP request against its catalog endpoint:

curl http://localhost:5000/v2/_catalog
# Expected response: {"repositories":[]}

Step 2: Create the Authentication Configuration

Create a file named auth.yaml to specify access permissions. Because the local registry runs over HTTP without TLS, add insecure: true for localhost:5000.

We do not need to add credentials for public Docker Hub images (like alpine), because image-syncer will automatically fall back to anonymous access when no matching credentials are found.

# auth.yaml
localhost:5000:
  insecure: true

Step 3: Define Synchronization Rules

Create a file named images.yaml containing the image synchronization rule mapping. In this example, we will sync a public Alpine Linux image from Docker Hub and push it to our local registry:

# images.yaml
alpine:3.18.2: "localhost:5000/image-syncer-test/alpine"

This format specifies that image-syncer should fetch docker.io/library/alpine:3.18.2 and write it to localhost:5000/image-syncer-test/alpine:3.18.2.

Step 4: Run the Synchronization Task

Execute image-syncer by pointing it to your auth and image configuration files. Use the --proc flag to control concurrency:

./image-syncer --auth=./auth.yaml --images=./images.yaml --proc=2

Understanding the CLI Output

When execution begins, the tool displays log messages showing its progress:

Generating sync tasks from alpine:3.18.2 to localhost:5000/image-syncer-test/alpine:3.18.2
Synchronizing blob sha256:3d380ca23841e2f7b8cb79... to localhost:5000/image-syncer-test/alpine:3.18.2
Synchronizing manifest from alpine:3.18.2 to localhost:5000/image-syncer-test/alpine:3.18.2
Synchronization finished, 0 tasks failed, cost 2.14s.

If the synchronization fails, inspect the output log. Common issues include connection timeouts or mismatched port configurations.

Step 5: Verify the Synchronized Image

Once the execution completes, verify that the image is available in the target local registry. You can check the registry's catalog endpoint:

curl http://localhost:5000/v2/_catalog
# Expected response: {"repositories":["image-syncer-test/alpine"]}

You can also verify the image by pulling it directly from your local registry using your local Docker daemon:

docker pull localhost:5000/image-syncer-test/alpine:3.18.2

Now that you have executed a basic synchronization task, see the Configuration Guide to learn how to write more complex rules, manage registry logins, and configure environment variables.