Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Getting started with Red Hat Quay

The Red Hat Quay registry can be deployed for non-production purposes on a single machine, either physical or virtual, with the following specifications.

2.1. Prerequisites
Copy link

  • Red Hat Enterprise Linux (RHEL) 8: Obtain the latest Red Hat Enterprise Linux 8 server media from the Downloads page and follow the installation instructions available in the Product Documentation for Red Hat Enterprise Linux 8.
  • Valid Red Hat Subscription: Configure a valid Red Hat Enterprise Linux 8 server subscription.
  • CPUs: Two or more virtual CPUs.
  • RAM: 4GB or more.

  • Disk space: The required disk space depends on the storage needs for the registry. Approximately 30GB of disk space should be enough for a test system, broken down as follows:

    • At least 10GB of disk space for the Red Hat Enterprise Linux operating system.
    • At least 10GB of disk space for docker storage (to run 3 containers).
    • At least 10GB of disk space for Quay local storage. Note that CEPH or other local storage might require more memory.

More information on sizing can be found at Quay 3.x Sizing Guidlines.

Note

Red Hat Enterprise Linux (RHEL) 8 is strongly recommended for highly available, production quality deployments of Red Hat Quay 3.7. RHEL 7 has not been tested with Red Hat Quay 3.7, and will be deprecated in a future release.

2.1.1. Using Podman
Copy link

This document uses Podman for creating and deploying containers. If you do not have Podman installed on your system, you should be able to use the equivalent Docker commands. For more information on Podman and related technologies, see Building, running, and managing Linux containers on Red Hat Enterprise Linux 8.

Note

Podman is strongly recommended for highly available, production quality deployments of Red Hat Quay 3.7. Docker has not been tested with Red Hat Quay 3.7, and will be deprecated in a future release.

2.2.1. Install and register the RHEL server
Copy link

  1. Install the latest RHEL 8 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 system…​.

  3. Use 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

2.2.2. Installing Podman
Copy link

  • Install Podman if it is not already on your system: 

    $ sudo yum install -y podman

  • Alternatively, you can install the container-tools module, which pulls in the full set of container software packages: 

    $ sudo yum module install -y container-tools

2.2.3. Registry authentication
Copy link

  • Set up authentication to registry.redhat.io, so that you can pull the Quay container, as described in Red Hat Container Registry Authentication. Note that this differs from earlier Red Hat Quay releases where the images were hosted on quay.io.

    You can log in to the registry using the following command: 

    $ sudo podman login registry.redhat.io
Username: <username>
Password: <password>

2.2.4. Firewall configuration
Copy link

  • If you have a firewall running on your system, you might have to add rules that allow access to Red Hat Quay. The commands required depend on the ports you have mapped, for example: 

    $ firewall-cmd --permanent --add-port=80/tcp
$ firewall-cmd --permanent --add-port=443/tcp
$ firewall-cmd --permanent --add-port=5432/tcp
$ firewall-cmd --permanent --add-port=5433/tcp
$ firewall-cmd --permanent --add-port=6379/tcp
$ firewall-cmd --reload

2.2.5. IP addressing and naming services
Copy link

There are a number of ways to configure the component containers in Red Hat Quay so that they can talk to each other:

  • Using the IP addresses for the containers: You can determine the IP address for containers with podman inspect and then use these values in the configuration tool when specifying the connection strings, for example: 

    $ sudo podman inspect -f "{{.NetworkSettings.IPAddress}}" postgresql-quay

    This approach is susceptible to host restarts, as the IP addresses for the containers will change after a reboot.

  • Using a naming service: If you want your deployment to survive container restarts, which typically result in changed IP addresses, you can implement a naming service. For example, the dnsname plugin is used to allow containers to resolve each other by name.
  • Using the host network: You can use the podman run command with the --net=host option and then use container ports on the host when specifying the addresses in the configuration. This option is susceptible to port conflicts when two containers want to use the same port, and as a result it is not recommended.
  • Configuring port mapping: You can use port mappings to expose ports on the host and then use these ports in combination with the host IP address or host name.

This document uses port mapping and assumes a static IP address for your host system. Throughout this deployment, we use quay-server.example.com with our system’s IP address, 192.168.1.112, and establish this information in the /etc/hosts file: 

$ cat /etc/hosts
...
192.168.1.112   quay-server.example.com
Expand
ComponentPort mappingAddress

Quay

-p 80:8080 -p 443:8443

http://quay-server.example.com

Postgres for Quay

-p 5432:5432

quay-server.example.com:5432

Redis

-p 6379:6379

quay-server.example.com:6379

Postgres for Clair V4

-p 5433:5432

quay-server.example.com:5433

Clair V4

-p 8081:8080

http://quay-server.example.com:8081

2.3. Configuring the database
Copy link

Quay requires a database for storing metadata. Postgres is used throughout this document and is recommended for highly available configurations. Alternatively, you can use MySQL with a similar approach to configuration as described below.

2.3.1. Setting up Postgres
Copy link

In this proof-of-concept scenario, you will use a directory on the local file system to persist database data.

  1. In the installation folder, denoted here by the variable $QUAY, create a directory for the database data and set the permissions appropriately: 

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

  2. Use podman run to start the Postgres container, specifying the username, password, database name and port, together 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-10:1

  3. Ensure that the Postgres pg_trgm module is installed, as it is required by Quay: 

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

2.4. Configuring Redis
Copy link

Redis ia a key-value store that is used by Quay for live builder logs and the Red Hat Quay tutorial.

2.4.1. Setting up Redis
Copy link

  • Use podman run to start the Redis container, specifying the port and password: 

    $ sudo podman run -d --rm --name redis \
  -p 6379:6379 \
  -e REDIS_PASSWORD=strongpassword \
  registry.redhat.io/rhel8/redis-5:1

2.5. Configuring Red Hat Quay
Copy link

Before running the Red Hat Quay service, you need to generate a configuration file that details of all the components, including registry settings, and database and Redis connection parameters.

  1. To generate a configuration file, run the Quay container in config mode, specifying a password, for example, the string secret. 

    $ sudo podman run --rm -it --name quay_config -p 80:8080 -p 443:8443 registry.redhat.io/quay/quay-rhel8:v3.7.13 config secret
  2. Use your browser to access the user interface for the configuration tool at http://quay-server.example.com. Note this documentation assumes you have configured the quay-server.example.com hostname in your /etc/hosts file.
  3. Log in with the username quayconfig and password secret, or whatever values were specified in the podman run command above.

2.5.1. Red Hat Quay setup
Copy link

In the configuration editor, the following details are entered:

  • Basic configuration
  • Server configuration
  • Database
  • Redis

2.5.1.1. Basic configuration
Copy link

In the basic configuration setting, complete the registry title and the registry short title fields. The default values can be used if they are populated.

2.5.1.2. Server configuration
Copy link

Specify the HTTP host and port for the location where the registry will be accessible on the network. If you followed the instructions in this document, enter quay-server.example.com.

2.5.1.3. Database
Copy link

In the database section, specify connection details for the database that Red Hat Quay uses to store metadata. If you followed the instructions in this document for deploying a proof-of-concept system, the following values would be entered:

  • Database Type: Postgres
  • Database Server: quay-server.example.com:5432
  • Username: quayuser
  • Password: quaypass
  • Database Name: quay

2.5.1.4. Redis
Copy link

The Redis key-value store is used to store real-time events and build logs. If you followed the instructions in this document for deploying a proof-of-concept system, the following values would be entered:

  • Redis Hostname: quay-server.example.com
  • Redis port: 6379 (default)
  • Redis password: strongpassword

2.5.2. Validate and download configuration
Copy link

When all required fields have been set, validate your settings by clicking Validate Configuration Changes. If any errors are reported, continue editing your configuration until all required fields are valid and Red Hat Quay can connect to your database and Redis servers.

Once your configuration is valid, download the configuration file. Stop the Quay container that is running the configuration editor.

2.6. Deploying Red Hat Quay
Copy link

2.6.1. Prerequisites
Copy link

  • Your Quay database and Redis servers are running.
  • You have generated a valid configuration bundle.
  • You have stopped the Quay container that you used to run the configuration editor.

2.6.2. Prepare config folder
Copy link

  • Unpack the configuration bundle so that Quay can use it: 

    $ mkdir $QUAY/config
$ cp ~/Downloads/quay-config.tar.gz $QUAY/config
$ cd $QUAY/config
$ tar xvf quay-config.tar.gz

2.6.3. Prepare local storage for image data
Copy link

  • For this proof-of-concept deployment, use the local file system to store the registry images: 

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

2.6.4. Deploy the Red Hat Quay registry
Copy link

  • Use podman run to start the Quay container. Specify the appropriate volumes for your 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.7.13

2.7. Using Red Hat Quay
Copy link

The following steps allow you to use the interface and create new organizations and repositories , and to search and browse existing repositories. Following step 3, you can use the command line interface to interact with the registry, and to push and pull images.

  1. Use your browser to access the user interface for the Red Hat Quay registry at http://quay-server.example.com, assuming you have configured quay-server.example.com as your hostname in your /etc/hosts file.
  2. Click Create Account and add a user, for example, quayadmin with a password password.

  3. From the command line, log in to the registry: 

    $ sudo podman login --tls-verify=false quay-server.example.com
Username: quayadmin
Password: password
Login Succeeded!

2.7.1. Push and pull images
Copy link

  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

  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
...

  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

  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

  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

  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
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top