Installation and Setup

image-syncer is designed as a standalone, lightweight tool with minimal system requirements. It can run as a pre-compiled binary, be built from source, run inside a lightweight container, or run as a step in automated CI/CD pipelines.

System Prerequisites

If you plan to compile the tool from source, verify your environment meets the following baseline dependencies:

• Go: Version 1.20 or newer is required (development and testing utilize Go 1.22.5 or newer).
• Make: Standard build automation utility (typically pre-installed on Linux and macOS).
• Git: Required to clone the repository and fetch dependencies.

For binary deployments or Docker runtimes, ensure your networking configuration permits outbound TCP connections to your source and destination registries on standard HTTPS ports (typically TCP port 443, or port 5000 for local development registries).

Pre-compiled Binaries

Pre-compiled, statically linked binaries for standard operating systems and hardware platforms are available on the GitHub Releases page.

Downloader Script for Linux/macOS

You can retrieve and extract the executable directly using standard command-line utilities. Below is an example workflow for installing the binary on a Linux AMD64 host:

# Define the target version
VERSION="v1.4.0"

# Download the release archive
curl -L -O "https://github.com/AliyunContainerService/image-syncer/releases/download/${VERSION}/image-syncer-${VERSION}-linux-amd64.tar.gz"

# Extract the archive
tar -zxvf "image-syncer-${VERSION}-linux-amd64.tar.gz"

# Move the binary to a directory in your system PATH
sudo mv image-syncer /usr/local/bin/

# Verify installation
image-syncer --version

Compiling From Source

For customized builds, or to compile for platforms not covered by official releases, build the binary using the Go toolchain.

# Fetch the repository via go get or git clone
git clone https://github.com/AliyunContainerService/image-syncer.git
cd image-syncer

# Build the binary using the provided Makefile
make

The compilation pipeline statically links dependencies, resulting in a single executable named image-syncer in the project root folder.

Containerized Execution

A multi-stage Dockerfile is included in the project repository. It compiles the source inside an isolated build environment and packages the output into a minimal container.

Multi-Stage Dockerfile Reference

FROM golang:1.22.5 as builder
WORKDIR /go/src/github.com/AliyunContainerService/image-syncer
COPY ./ ./
ENV GOPROXY=https://proxy.golang.com.cn,direct
RUN CGO_ENABLED=0 GOOS=linux make

FROM alpine:latest
WORKDIR /bin/
COPY --from=builder /go/src/github.com/AliyunContainerService/image-syncer/image-syncer ./
RUN chmod +x ./image-syncer
RUN apk add -U --no-cache ca-certificates && rm -rf /var/cache/apk/* && mkdir -p /etc/ssl/certs \
  && update-ca-certificates --fresh
ENTRYPOINT ["image-syncer"]
CMD ["--config", "/etc/image-syncer/image-syncer.json"]

Running with Docker

To build and run the image locally, use the following commands:

# Build the Docker image
docker build -t image-syncer:latest .

# Execute a sync task by mounting configuration files from your host system
docker run --rm \
  -v $(pwd)/auth.yaml:/etc/image-syncer/auth.yaml \
  -v $(pwd)/images.yaml:/etc/image-syncer/images.yaml \
  image-syncer:latest \
  --auth /etc/image-syncer/auth.yaml \
  --images /etc/image-syncer/images.yaml

Ensure that the file paths mounted using -v align with where your auth.yaml and images.yaml are located on the host. For details on how to write these files, see the Configuration Guide.

CI/CD Pipeline Integration

Integrating image synchronization into automated delivery workflows helps keep test, staging, and production registries aligned.

GitHub Actions Integration

You can use the image-sync-action in your workflows. This action runs on GitHub-hosted runners, requiring no dedicated server resources.

name: Synchronize Container Images

on:
  schedule:
    - cron: '0 2 * * *' # Run daily at 02:00 UTC
  workflow_dispatch: # Allow manual execution

jobs:
  sync-images:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Run Image Syncer Action
        uses: AliyunContainerService/image-sync-action@v1
        with:
          auth_file: './auth.yaml'
          images_file: './images.yaml'
          proc: '6'
          retries: '3'

To configure and run your first manual synchronization pipeline, proceed to the Quick Start Guide.