Deploy Red Hat Quay for proof-of-concept (non-production) purposes

Procedure

1. Install the latest RHEL 9 server. You can do a minimal, shell-access only install, or Server plus GUI if you want a desktop.
2. Register and subscribe your RHEL server system as described in How to register and subscribe a RHEL system to the Red Hat Customer Portal using Red Hat Subscription-Manager

3. Enter the following commands to register your system and list available subscriptions. Choose an available RHEL server subscription, attach to its pool ID, and upgrade to the latest software:

   # subscription-manager register --username=<user_name> --password=<password>
   # subscription-manager refresh
   # subscription-manager list --available
   # subscription-manager attach --pool=<pool_id>
   # yum update -y

   Copy to Clipboard Toggle word wrap

Procedure

1. Set up authentication to registry.redhat.io by following the Red Hat Container Registry Authentication procedure. Setting up authentication allows you to pull the Quay container.

   Note

   This differs from earlier versions of Red Hat Quay, when the images were hosted on Quay.io.

2. Enter the following command to log in to the registry:

   $ sudo podman login registry.redhat.io

   Copy to Clipboard Toggle word wrap

   You are prompted to enter your username and password.

Procedure

1. In the installation folder, denoted here by the $QUAY variable, create a directory for the database data by entering the following command:

   $ mkdir -p $QUAY/postgres-quay

   Copy to Clipboard Toggle word wrap

2. Set the appropriate permissions by entering the following command:

   $ setfacl -m u:26:-wx $QUAY/postgres-quay

   Copy to Clipboard Toggle word wrap

3. Start the Postgres container, specifying the username, password, and database name and port, with the volume definition for database data:

   $ sudo podman run -d --rm --name postgresql-quay \
     -e POSTGRESQL_USER=quayuser \
     -e POSTGRESQL_PASSWORD=quaypass \
     -e POSTGRESQL_DATABASE=quay \
     -e POSTGRESQL_ADMIN_PASSWORD=adminpass \
     -p 5432:5432 \
     -v $QUAY/postgres-quay:/var/lib/pgsql/data:Z \
     registry.redhat.io/rhel8/postgresql-13

   Copy to Clipboard Toggle word wrap

4. Ensure that the Postgres pg_trgm module is installed by running the following command:

   $ sudo podman exec -it postgresql-quay /bin/bash -c 'echo "CREATE EXTENSION IF NOT EXISTS pg_trgm" | psql -d quay -U postgres'

   Copy to Clipboard Toggle word wrap
   Note

   The pg_trgm module is required for the Quay container.

Procedure

1. Create a directory to copy the Red Hat Quay configuration bundle to:

   $ mkdir $QUAY/config

   Copy to Clipboard Toggle word wrap

2. Copy the generated Red Hat Quay configuration bundle to the directory:

   $ cp ~/Downloads/quay-config.tar.gz ~/config

   Copy to Clipboard Toggle word wrap

3. Change into the the directory:

   $ cd $QUAY/config

   Copy to Clipboard Toggle word wrap

4. Unpack the Red Hat Quay configuration bundle:

   $ tar xvf quay-config.tar.gz

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a local directory that will store registry images by entering the following command:

   $ mkdir $QUAY/storage

   Copy to Clipboard Toggle word wrap

2. Set the directory to store registry images:

   $ setfacl -m u:1001:-wx $QUAY/storage

   Copy to Clipboard Toggle word wrap

1. Use the following procedure to deploy the Quay registry container.

2. Enter the following command to start the Quay registry container, specifying the appropriate volumes for configuration data and local storage for image data:

   $ sudo podman run -d --rm -p 80:8080 -p 443:8443  \
      --name=quay \
      -v $QUAY/config:/conf/stack:Z \
      -v $QUAY/storage:/datastorage:Z \
      registry.redhat.io/quay/quay-rhel8:v3.9.15

   Copy to Clipboard Toggle word wrap

1. To test pushing and pulling images from the Red Hat Quay registry, first pull a sample image from an external registry:

   $ sudo podman pull busybox
   Trying to pull docker.io/library/busybox...
   Getting image source signatures
   Copying blob 4c892f00285e done
   Copying config 22667f5368 done
   Writing manifest to image destination
   Storing signatures
   22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9

   Copy to Clipboard Toggle word wrap

2. Use the podman images command to see the local copy:

   $ sudo podman images
   REPOSITORY                          TAG      IMAGE ID       CREATED         SIZE
   docker.io/library/busybox           latest   22667f53682a   14 hours ago    1.45 MB
   ...

   Copy to Clipboard Toggle word wrap

3. Tag this image, in preparation for pushing it to the Red Hat Quay registry:

   $ sudo podman tag docker.io/library/busybox quay-server.example.com/quayadmin/busybox:test

   Copy to Clipboard Toggle word wrap

4. Next, push the image to the Red Hat Quay registry. Following this step, you can use your browser to see the tagged image in your repository.

   $ sudo podman push --tls-verify=false quay-server.example.com/quayadmin/busybox:test
   Getting image source signatures
   Copying blob 6b245f040973 done
   Copying config 22667f5368 done
   Writing manifest to image destination
   Storing signatures

   Copy to Clipboard Toggle word wrap

5. To test access to the image from the command line, first delete the local copy of the image:

   $ sudo podman rmi quay-server.example.com/quayadmin/busybox:test
   Untagged: quay-server.example.com/quayadmin/busybox:test

   Copy to Clipboard Toggle word wrap

6. Pull the image again, this time from your Red Hat Quay registry:

   $ sudo podman pull --tls-verify=false quay-server.example.com/quayadmin/busybox:test
   Trying to pull quay-server.example.com/quayadmin/busybox:test...
   Getting image source signatures
   Copying blob 6ef22a7134ba [--------------------------------------] 0.0b / 0.0b
   Copying config 22667f5368 done
   Writing manifest to image destination
   Storing signatures
   22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9

   Copy to Clipboard Toggle word wrap

Procedure

1. Start the Quay container in configuration mode:

   $ sudo podman run --rm -it --name quay_config -p 80:8080 -p 443:8443 registry.redhat.io/quay/quay-rhel8:v3.9.15 config secret

   Copy to Clipboard Toggle word wrap
2. In the Server Configuration section, select Red Hat Quay handles TLS for SSL/TLS. Upload the certificate file and private key file created earlier, ensuring that the Server Hostname matches the value used when the certificates were created.
3. Validate and download the updated configuration.

4. Stop the Quay container and then restart the registry by entering the following command:

   $ sudo podman rm -f quay
   $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
   --name=quay \
   -v $QUAY/config:/conf/stack:Z \
   -v $QUAY/storage:/datastorage:Z \
   registry.redhat.io/quay/quay-rhel8:v3.9.15

   Copy to Clipboard Toggle word wrap

Procedure

1. Copy the certificate file and primary key file to your configuration directory, ensuring they are named ssl.cert and ssl.key respectively:

   cp ~/ssl.cert ~/ssl.key $QUAY/config

   Copy to Clipboard Toggle word wrap

2. Change into the $QUAY/config directory by entering the following command:

   $ cd $QUAY/config

   Copy to Clipboard Toggle word wrap

3. Edit the config.yaml file and specify that you want Red Hat Quay to handle TLS/SSL:

   config.yaml

   ...
   SERVER_HOSTNAME: quay-server.example.com
   ...
   PREFERRED_URL_SCHEME: https
   ...

   Copy to Clipboard Toggle word wrap

4. Optional: Append the contents of the rootCA.pem file to the end of the ssl.cert file by entering the following command:

   $ cat rootCA.pem >> ssl.cert

   Copy to Clipboard Toggle word wrap

5. Stop the Quay container by entering the following command:

   $ sudo podman stop quay

   Copy to Clipboard Toggle word wrap

6. Restart the registry by entering the following command:

   $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
     --name=quay \
     -v $QUAY/config:/conf/stack:Z \
     -v $QUAY/storage:/datastorage:Z \
     registry.redhat.io/quay/quay-rhel8:v3.9.15

   Copy to Clipboard Toggle word wrap

Procedure

1. Enter the following command to copy the rootCA.pem file to the consolidated system-wide trust store:

   $ sudo cp rootCA.pem /etc/pki/ca-trust/source/anchors/

   Copy to Clipboard Toggle word wrap

2. Enter the following command to update the system-wide trust store configuration:

   $ sudo update-ca-trust extract

   Copy to Clipboard Toggle word wrap

3. Optional. You can use the trust list command to ensure that the Quay server has been configured:

   $ trust list | grep quay
       label: quay-server.example.com

   Copy to Clipboard Toggle word wrap

   Now, when you browse to the registry at https://quay-server.example.com, the lock icon shows that the connection is secure:

   

4. To remove the rootCA.pem file from system-wide trust, delete the file and update the configuration:

   $ sudo rm /etc/pki/ca-trust/source/anchors/rootCA.pem

   Copy to Clipboard Toggle word wrap

   $ sudo update-ca-trust extract

   Copy to Clipboard Toggle word wrap

   $ trust list | grep quay

   Copy to Clipboard Toggle word wrap

1. Start the Quay container in configuration mode, loading the existing configuration as a volume:

   $ sudo podman run --rm -it --name quay_config \
     -p 8080:8080 \
     -p 443:8443 \
     -v $QUAY/config:/conf/stack:Z \
     registry.redhat.io/quay/quay-rhel8:v3.9.15 config secret

   Copy to Clipboard Toggle word wrap
2. Under the Access Settings section of the UI, enter the name of the user (in this instance, quayadmin) in the Super Users field and click Add.

3. Validate and download the configuration file and then terminate the Quay container that is running in config mode. Extract the config.yaml file to the configuration directory and restart the Quay container in registry mode:

   $ sudo podman rm -f quay
   $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
   --name=quay \
   -v $QUAY/config:/conf/stack:Z \
   -v $QUAY/storage:/datastorage:Z \
   registry.redhat.io/quay/quay-rhel8:v3.9.15

   Copy to Clipboard Toggle word wrap

1. Restart the Quay registry:

   $ sudo podman rm -f quay
   $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
   --name=quay \
   -v $QUAY/config:/conf/stack:Z \
   -v $QUAY/storage:/datastorage:Z \
   registry.redhat.io/quay/quay-rhel8:v3.9.15

   Copy to Clipboard Toggle word wrap

2. Access the Super User Admin Panel by clicking on the current user’s name or avatar in the top right-hand corner of the UI. If the user has been added as a superuser, an extra item is presented in the drop-down list called Super User Admin Panel.

   

1. Start the Quay container in configuration mode and select the Enable Repository Mirroring check box. If you want to require HTTPS communications and verify certificates during mirroring, select the HTTPS and cert verification check box.

   

2. Validate and download the configuration file, and then restart Quay in registry mode using the updated config file.

Procedure

1. In your Red Hat Quay installation directory, create a new directory for the Clair database data:

   $ mkdir /home/<user-name>/quay-poc/postgres-clairv4

   Copy to Clipboard Toggle word wrap

2. Set the appropriate permissions for the postgres-clairv4 file by entering the following command:

   $ setfacl -m u:26:-wx /home/<user-name>/quay-poc/postgres-clairv4

   Copy to Clipboard Toggle word wrap

3. Deploy a Clair Postgres database by entering the following command:

   $ sudo podman run -d --name postgresql-clairv4 \
     -e POSTGRESQL_USER=clairuser \
     -e POSTGRESQL_PASSWORD=clairpass \
     -e POSTGRESQL_DATABASE=clair \
     -e POSTGRESQL_ADMIN_PASSWORD=adminpass \
     -p 5433:5433 \
     -v /home/<user-name>/quay-poc/postgres-clairv4:/var/lib/pgsql/data:Z \
     registry.redhat.io/rhel8/postgresql-13:1-109

   Copy to Clipboard Toggle word wrap

4. Install the Postgres uuid-ossp module for your Clair deployment:

   $ podman exec -it postgresql-clairv4 /bin/bash -c 'echo "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\"" | psql -d clair -U postgres'

   Copy to Clipboard Toggle word wrap

   Example output

   CREATE EXTENSION

   Copy to Clipboard Toggle word wrap

   Note

   Clair requires the uuid-ossp extension to be added to its Postgres database. For users with proper privileges, creating the extension will automatically be added by Clair. If users do not have the proper privileges, the extension must be added before start Clair.

   If the extension is not present, the following error will be displayed when Clair attempts to start: ERROR: Please load the "uuid-ossp" extension. (SQLSTATE 42501).

5. Stop the Quay container if it is running and restart it in configuration mode, loading the existing configuration as a volume:

   $ sudo podman run --rm -it --name quay_config \
     -p 80:8080 -p 443:8443 \
     -v $QUAY/config:/conf/stack:Z \
     registry.redhat.io/quay/quay-rhel8:{productminv} config secret

   Copy to Clipboard Toggle word wrap
6. Log in to the configuration tool and click Enable Security Scanning in the Security Scanner section of the UI.
7. Set the HTTP endpoint for Clair using a port that is not already in use on the quay-server system, for example, 8081.

8. Create a pre-shared key (PSK) using the Generate PSK button.

   Security Scanner UI

   

9. Validate and download the config.yaml file for Red Hat Quay, and then stop the Quay container that is running the configuration editor.

10. Extract the new configuration bundle into your Red Hat Quay installation directory, for example:

    $ tar xvf quay-config.tar.gz -d /home/<user-name>/quay-poc/

    Copy to Clipboard Toggle word wrap

11. Create a folder for your Clair configuration file, for example:

    $ mkdir /etc/opt/clairv4/config/

    Copy to Clipboard Toggle word wrap

12. Change into the Clair configuration folder:

    $ cd /etc/opt/clairv4/config/

    Copy to Clipboard Toggle word wrap

13. Create a Clair configuration file, for example:

    http_listen_addr: :8081
    introspection_addr: :8088
    log_level: debug
    indexer:
      connstring: host=quay-server.example.com port=5433 dbname=clair user=clairuser password=clairpass sslmode=disable
      scanlock_retry: 10
      layer_scan_concurrency: 5
      migrations: true
    matcher:
      connstring: host=quay-server.example.com port=5433 dbname=clair user=clairuser password=clairpass sslmode=disable
      max_conn_pool: 100
      migrations: true
      indexer_addr: clair-indexer
    notifier:
      connstring: host=quay-server.example.com port=5433 dbname=clair user=clairuser password=clairpass sslmode=disable
      delivery_interval: 1m
      poll_interval: 5m
      migrations: true
    auth:
      psk:
        key: "MTU5YzA4Y2ZkNzJoMQ=="
        iss: ["quay"]
    # tracing and metrics
    trace:
      name: "jaeger"
      probability: 1
      jaeger:
        agent:
          endpoint: "localhost:6831"
        service_name: "clair"
    metrics:
      name: "prometheus"

    Copy to Clipboard Toggle word wrap

    For more information about Clair’s configuration format, see Clair configuration reference.

14. Start Clair by using the container image, mounting in the configuration from the file you created:

    $ sudo podman run -d --name clairv4 \
    -p 8081:8081 -p 8088:8088 \
    -e CLAIR_CONF=/clair/config.yaml \
    -e CLAIR_MODE=combo \
    -v /etc/opt/clairv4/config:/clair:Z \
    registry.redhat.io/quay/clair-rhel8:v3.9.15

    Copy to Clipboard Toggle word wrap
    Note

    Running multiple Clair containers is also possible, but for deployment scenarios beyond a single container the use of a container orchestrator like Kubernetes or OpenShift Container Platform is strongly recommended.

Procedure

1. Pull a sample image by entering the following command:

   $ podman pull ubuntu:20.04

   Copy to Clipboard Toggle word wrap

2. Tag the image to your registry by entering the following command:

   $ sudo podman tag docker.io/library/ubuntu:20.04 <quay-server.example.com>/<user-name>/ubuntu:20.04

   Copy to Clipboard Toggle word wrap

3. Push the image to your Red Hat Quay registry by entering the following command:

   $ sudo podman push --tls-verify=false quay-server.example.com/quayadmin/ubuntu:20.04

   Copy to Clipboard Toggle word wrap
4. Log in to your Red Hat Quay deployment through the UI.
5. Click the repository name, for example, quayadmin/ubuntu.

6. In the navigation pane, click Tags.

   Report summary

   

7. Click the image report, for example, 45 medium, to show a more detailed report:

   Report details

   

   Note

   In some cases, Clair shows duplicate reports on images, for example, ubi8/nodejs-12 or ubi8/nodejs-16. This occurs because vulnerabilities with same name are for different packages. This behavior is expected with Clair vulnerability reporting and will not be addressed as a bug.

1. Create the systemd unit files from a running Red Hat Quay registry as follows:

   $ sudo podman generate systemd --new --files --name redis
   $ sudo podman generate systemd --new --files --name postgresql-quay
   $ sudo podman generate systemd --new --files --name quay
   $ sudo podman generate systemd --new --files --name postgresql-clairv4
   $ sudo podman generate systemd --new --files --name clairv4

   Copy to Clipboard Toggle word wrap

2. Copy the unit files to /usr/lib/systemd/system for installing them as a root user:

   $ sudo cp -Z container-redis.service /usr/lib/systemd/system
   $ sudo cp -Z container-postgresql-quay.service /usr/lib/systemd/system
   $ sudo cp -Z container-quay.service /usr/lib/systemd/system
   $ sudo cp -Z container-postgresql-clairv4.service /usr/lib/systemd/system
   $ sudo cp -Z container-clairv4.service /usr/lib/systemd/system

   Copy to Clipboard Toggle word wrap

3. Reload systemd manager configuration:

   $ sudo systemctl daemon-reload

   Copy to Clipboard Toggle word wrap

4. Enable the services and start them at boot time:

   $ sudo systemctl enable --now container-redis.service
   $ sudo systemctl enable --now container-postgresql-quay.service
   $ sudo systemctl enable --now container-quay.service
   $ sudo systemctl enable --now container-postgresql-clairv4.service
   $ sudo systemctl enable --now container-clairv4.service

   Copy to Clipboard Toggle word wrap

1. Check the status of the Quay components:

   $ sudo systemctl status container-redis.service
   $ sudo systemctl status container-postgresql-quay.service
   $ sudo systemctl status container-quay.service
   $ sudo systemctl status container-postgresql-clairv4.service
   $ sudo systemctl status container-clairv4.service

   Copy to Clipboard Toggle word wrap

2. To stop the Quay component services:

   $ sudo systemctl stop container-redis.service
   $ sudo systemctl stop container-postgresql-quay.service
   $ sudo systemctl stop container-quay.service
   $ sudo systemctl stop container-postgresql-clairv4.service
   $ sudo systemctl stop container-clairv4.service

   Copy to Clipboard Toggle word wrap

3. To start the Quay component services:

   $ sudo systemctl start container-redis.service
   $ sudo systemctl start container-postgresql-quay.service
   $ sudo systemctl start container-quay.service
   $ sudo systemctl start container-postgresql-clairv4.service
   $ sudo systemctl start container-clairv4.service

   Copy to Clipboard Toggle word wrap