Quickstart

Quickstart guide and demo for Portward.

Warning

Project is under development. Backwards compatibility is not guaranteed.

Prerequisites

Docker (with Compose)
A registry client:
- skopeo
- regclient
just optional

Download an image archive (for example alpine) that you can push to registries.

Using skopeo:

mkdir -p var/
skopeo --insecure-policy copy -a docker://docker.io/library/alpine:latest oci-archive://$PWD/var/alpine.tar.gz

Using regctl:

mkdir -p var/
regctl image export docker.io/library/alpine:latest $PWD/var/alpine.tar.gz

For an optimal developer experience, it is recommended to install Nix and direnv.

Usage

Create a config.yaml file:

cp config.example.yaml config.yaml

Important

Restart portward using docker compose restart portward if you change anything in config.yaml.

Start Docker Compose:

docker compose up -d

Note

Check the docker-compose.yaml file for ports and make sure they are not in use.

Make sure containers are started:

docker compose ps

Decide which registry you want to use:

Distribution: export REGISTRY=127.0.0.1:5000
Zot: export REGISTRY=127.0.0.1:5001

Admin use case

# Using skopeo
skopeo login --tls-verify=false -u admin -p password $REGISTRY

# Using regctl
regctl registry set --tls=disabled $REGISTRY
regctl registry login -u user -p password $REGISTRY

Push images to the registry:

# Using skopeo
skopeo --insecure-policy copy --dest-tls-verify=false -a oci-archive://$PWD/var/alpine.tar.gz docker://$REGISTRY/alpine
skopeo --insecure-policy copy --dest-tls-verify=false -a oci-archive://$PWD/var/alpine.tar.gz docker://$REGISTRY/product1/alpine

# Using regctl
regctl image import $REGISTRY/alpine $PWD/var/alpine.tar.gz
regctl image import $REGISTRY/product1/alpine $PWD/var/alpine.tar.gz

Logout as admin from the registry:

# Using skopeo
skopeo logout $REGISTRY

# Using regctl
regctl registry logout $REGISTRY

User use case

# Using skopeo
skopeo login --tls-verify=false -u user -p password $REGISTRY

# Using regctl
regctl registry set --tls=disabled $REGISTRY
regctl registry login -u user -p password $REGISTRY

Inspect and pull images in the registry:

# Using skopeo
skopeo --insecure-policy --override-os linux --override-arch amd64 inspect --tls-verify=false docker://$REGISTRY/alpine
skopeo --insecure-policy copy --src-tls-verify=false -a docker://$REGISTRY/alpine oci-archive:///dev/null

# Using regctl
regctl image inspect $REGISTRY/alpine
regctl image export $REGISTRY/alpine /dev/null

Try pulling an image user does not have access to:

# Using skopeo
skopeo --insecure-policy --override-os linux --override-arch amd64 inspect --tls-verify=false docker://$REGISTRY/product1/alpine
skopeo --insecure-policy copy --src-tls-verify=false -a docker://$REGISTRY/product1/alpine oci-archive:///dev/null

# Using regctl
regctl image inspect $REGISTRY/product1/alpine
regctl image export $REGISTRY/product1/alpine /dev/null

Push an image to the registry:

# Using skopeo
skopeo --insecure-policy copy --dest-tls-verify=false -a oci-archive://$PWD/var/alpine.tar.gz docker://$REGISTRY/user/alpine

# Using regctl
regctl image import $REGISTRY/user/alpine $PWD/var/alpine.tar.gz

Try pushing an image that user does not have access to:

# Using skopeo
skopeo --insecure-policy copy --dest-tls-verify=false -a oci-archive://$PWD/var/alpine.tar.gz docker://$REGISTRY/alpine

# Using regctl
regctl image import $REGISTRY/alpine $PWD/var/alpine.tar.gz

Logout as user from the registry:

# Using skopeo
skopeo logout $REGISTRY

# Using regctl
regctl registry logout $REGISTRY

Customer use case

# Using skopeo
skopeo login --tls-verify=false -u customer -p password $REGISTRY

# Using regctl
regctl registry set --tls=disabled $REGISTRY
regctl registry login -u customer -p password $REGISTRY

Inspect and pull images in the registry:

# Using skopeo
skopeo --insecure-policy --override-os linux --override-arch amd64 inspect --tls-verify=false docker://$REGISTRY/product1/alpine
skopeo --insecure-policy copy --src-tls-verify=false -a docker://$REGISTRY/product1/alpine oci-archive:///dev/null

# Using regctl
regctl image inspect $REGISTRY/product1/alpine
regctl image export $REGISTRY/product1/alpine /dev/null

Try pulling an image customer does not have access to:

# Using skopeo
skopeo --insecure-policy --override-os linux --override-arch amd64 inspect --tls-verify=false docker://$REGISTRY/alpine
skopeo --insecure-policy copy --src-tls-verify=false -a docker://$REGISTRY/alpine oci-archive:///dev/null

# Using regctl
regctl image inspect $REGISTRY/alpine
regctl image export $REGISTRY/alpine /dev/null

Try pushing an image as customer:

# Using skopeo
skopeo --insecure-policy copy --dest-tls-verify=false -a oci-archive://$PWD/var/alpine.tar.gz docker://$REGISTRY/customer/alpine

# Using regctl
regctl image import $REGISTRY/customer/alpine $PWD/var/alpine.tar.gz

Logout as customer from the registry:

# Using skopeo
skopeo logout $REGISTRY

# Using regctl
regctl registry logout $REGISTRY

Cleanup

Tear down the Docker Compose setup:

docker compose down -v

Remove files:

rm -rf var/

License

The project is licensed under the MIT License.

portward/quickstart