regclient/docs/regsync-quickstart.md

regsync Quick Start

Setup a Registry

docker network create registry
docker run -d --restart=unless-stopped --name registry --net registry \
  -e "REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry" \
  -e "REGISTRY_STORAGE_DELETE_ENABLED=true" \
  -e "REGISTRY_VALIDATION_DISABLED=true" \
  -v "registry-data:/var/lib/registry" \
  -p "127.0.0.1:5000:5000" \
  registry:2

Configure a Sync Yaml

Create a file called regsync.yml:

version: 1
creds:
  - registry: registry:5000
    tls: disabled
  - registry: docker.io
    user: "{{env \"HUB_USER\"}}"
    pass: "{{file \"/home/appuser/.docker/hub_token\"}}"
defaults:
  ratelimit:
    min: 100
    retry: 15m
  parallel: 2
  interval: 60m
  backup: "bkup-{{.Ref.Tag}}"
sync:
  - source: busybox:latest
    target: registry:5000/library/busybox:latest
    type: image
  - source: alpine
    target: registry:5000/library/alpine
    type: repository
    tags:
      allow:
      - "latest"
      - "3"
      - "3.\\d+"
  - source: ghcr.io/regclient/regctl:latest
    target: registry:5000/regclient/regctl:latest
    type: image

You'll also need to create a ${HOME}/.docker/hub_token file that includes either your hub password or a personal access token.

Test regsync

Run regsync in the "once" mode to populate your registry according to the above yaml. Make sure to replace your_username with your Hub username. Note that this command will pull a number of images from Hub, but will automatically rate limit itself if you have less than 100 pulls remaining on your account.

export HUB_USER=your_username
mkdir -p ${HOME}/.docker
echo "your_hub_password" >${HOME}/.docker/hub_token
docker container run -i --rm --net registry \
  -v "$(pwd)/regsync.yml:/home/appuser/regsync.yml:ro" \
  -v "${HOME}/.docker/hub_token:/home/appuser/.docker/hub_token:ro" \
  -e "HUB_USER" \
  ghcr.io/regclient/regsync:latest -c /home/appuser/regsync.yml once

Run regsync

Once the one time sync looks good, deploy a regsync service in the background:

docker container run -d --restart=unless-stopped --name regsync --net registry \
  -v "$(pwd)/regsync.yml:/home/appuser/regsync.yml:ro" \
  -v "$(pwd)/hub_token:/var/run/secrets/hub_token:ro" \
  -e "HUB_USER" \
  ghcr.io/regclient/regsync:latest -c /home/appuser/regsync.yml server

You can verify it started by checking the logs with docker container logs regsync. In server mode, no logs will show until the next scheduled run. In the above example, that would be 60 minutes. And then, the only output you'll see is when a new image gets pulled.

Use your registry

Now you can run images from your registry or build new images with the above base:

docker container run -i --rm localhost:5000/library/busybox echo hello world

In your Dockerfile, you can adjust the registry with a build arg:

ARG registry=docker.io
ARG tag=3
FROM ${registry}/library/alpine:${tag}
CMD echo "The time is now $(date)"

Build that image:

docker image build \
  --build-arg registry=localhost:5000 \
  -t localhost:5000/time .

Try running it:

docker container run --rm localhost:5000/time

Push to your local registry:

docker image push localhost:5000/time

Inspect using regctl

cat >regctl <<EOF
#!/bin/sh
opts=""
case "\$*" in
  "registry login"*) opts="-t";;
esac
docker container run \$opts -i --rm --net host \\
  -u "\$(id -u):\$(id -g)" -e HOME -v \$HOME:\$HOME \\
  -v /etc/docker/certs.d:/etc/docker/certs.d:ro \\
  ghcr.io/regclient/regctl:latest "\$@"
EOF
chmod 755 regctl
./regctl registry set --tls disabled localhost:5000
./regctl repo ls localhost:5000

You should see all the repositories setup by regsync.

./regctl tag ls localhost:5000/library/alpine

That shows all the tags copied.

./regctl image manifest --list localhost:5000/library/alpine:3

And there we can see that regsync pulled the multi-platform image from upstream, something that would be non-trivial with a docker pull and docker push command.