Red Hat Quay is an enterprise-quality container registry rebranded after the acquisition of CoreOS Quay Enterprise by Red Hat. Red Hat Quay registry is used to build and store containers, which are later deployed to the servers across your enterprise container platforms such as Kubernetes, OpenShift Container Platform e.t.c.
Check the Operator guide for installation on OpenShift:
Install Project Quay Registry on OpenShift With Operator
Features of Quay Registry
The top features of Quay include:
- High availability design
- Support for Geo-replication
- Support for Docker v2, schema 2 (multiarch)
- Best integration with Continuous integration pipelines
- Support for a custom log rotation
- Support for various Authentication, access methods, and storage backends
- Automated scanning for Security vulnerabilities
This guide will discuss the steps used to setup a single instance Quay Registry. This setup is for POC purposes and is not intended for use as a production install. For Highly available Quay registry, consult official Red Hat documentation.
Red Hat Quay Components
The three core components of Simple Quay setup are:
- Database: Used by Red Hat Quay as its primary metadata storage (not for image storage).
- Redis: Used as a key/value store for providing real-time events.
- Quay (container registry): Runs the quay container as a service, consisting of several components in the pod.
Setup Hardware Minimum requirements
This setup requires a physical or virtual machine with the following minimum hardware requirements.
- Memory: 4 GB
- CPUs: 2
- Disk Space: 30GB
- At least 10GB of disk space for docker storage (to run 3 containers)
- At least 10GB of disk space for Quay local storage (CEPH or other local storage might require more memory)
Below are the steps used to install and configure Red Hat Quay Registry on CentOS / RHEL / Rocky / AlmaLinux / Debian / Ubuntu and Arch based Linux distributions.
Step 1: Install Podman
Podman is used to run Quay containers, install it on your system using our guides below.
# Debian-based systems
sudo apt update && sudo apt install podman
# RHEL based systems
sudo yum -y install podman
Confirm installation by checking the version of Podman:
$ podman --version
podman version 4.9.3
Step 2: Set registry.redhat.io authentication
To be able to pull Quay container images, you need to set up authentication to registry.redhat.io
. Follow the Red Hat Container Registry Authentication procedure. In older earlier versions of Red Hat Quay, the images were hosted on Quay.io.
Run the following command to log in to the registry:
sudo podman login registry.redhat.io
You will get a prompt to enter your username
and password
.
Username: <your-redhat-account-username>
Password: <your-redhat-account-password>
Login Succeeded!
Step 3: Set up PostgreSQL Database
Quay uses database to store metadata. PostgreSQL will be used in this article.
Create directory for quay PostgreSQL data.
sudo mkdir -p ~/quay/postgres
Run the following commands to set appropriate permissions.
sudo setfacl -m u:26:-wx ~/quay/postgres
The commands below are used to start Postgres
container, specifying the username, password, and database name and port, with the volume definition for database data:
sudo podman run -d --name postgresql-quay \
-e POSTGRESQL_USER=quay \
-e POSTGRESQL_PASSWORD=Str0ngQuayPass0rd \
-e POSTGRESQL_DATABASE=quay \
-e POSTGRESQL_ADMIN_PASSWORD=Str0ngAdminPass0rd \
-p 5432:5432 \
-v ~/quay/postgres:/var/lib/pgsql/data:Z \
registry.redhat.io/rhel8/postgresql-16
Check container status:
$ sudo podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1f9e6943b7ec registry.redhat.io/rhel8/postgresql-16:latest run-postgresql 57 seconds ago Up 57 seconds 0.0.0.0:5432->5432/tcp postgresql-quay
Install the Postgres pg_trgm
module required for the Quay
container.
sudo podman exec -it postgresql-quay /bin/bash -c 'echo "CREATE EXTENSION IF NOT EXISTS pg_trgm" | psql -d quay -U postgres'
Step 4: Set up Redis Server
Red Hat Quay use redis as a key-value store for live builder logs. We are going to deploy the Redis
container for the Red Hat Quay using Podman.
sudo podman run -d --name redis-quay \
-p 6379:6379 \
-e REDIS_PASSWORD=StrongRedisPassw0rd \
registry.redhat.io/rhel8/redis-6
Check if Redis container is started successfully
$ sudo podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1f9e6943b7ec registry.redhat.io/rhel8/postgresql-16:latest run-postgresql 4 minutes ago Up 4 minutes 0.0.0.0:5432->5432/tcp postgresql-quay
2b1e65c3fe6f registry.redhat.io/rhel8/redis-6:latest run-redis 7 seconds ago Up 8 seconds 0.0.0.0:6379->6379/tcp redis-quay
Step 5: Deploy Red Hat Quay in Container
Before we can deploy Quay ensure the following prerequisites are met:
- The Red Hat Quay database is running.
- The Redis server is running.
- Configure Red Hat Quay endpoint (FQDN). In this example we are using quay.computingforgeeks.com
If you don’t have a DNS server, add the IP address and a local hostname to your /etc/hosts
$ sudo vim /etc/hosts
192.168.1.25 quay.example.com
Create a local directory that will store registry images
sudo mkdir ~/quay/storage
sudo setfacl -m u:1001:-wx ~/quay/storage
Create a directory to store Red Hat Quay configuration bundle:
sudo mkdir ~/quay/config
Red Hat Quay container requires configuration file to start. Create a minimal config file for Quay.
sudo vim ~/quay/config/config.yaml
Add and modify the following contents. Here we are using hostname quay.example.com as configured in /etc/hosts
file.
BUILDLOGS_REDIS:
host: quay.example.com
password: StrongRedisPassw0rd
port: 6379
CREATE_NAMESPACE_ON_PUSH: true
DATABASE_SECRET_KEY: a8c2744b-7004-4af2-bcee-e417e7bdd235
DB_URI: postgresql://quay:Str0ngQuayPass0rd@quay.example.com:5432/quay
DISTRIBUTED_STORAGE_CONFIG:
default:
- LocalStorage
- storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
- default
FEATURE_MAILING: false
SECRET_KEY: e9bd34f4-900c-436a-979e-7530e5d74ac8
SERVER_HOSTNAME: quay.example.com
SETUP_COMPLETE: true
USER_EVENTS_REDIS:
host: quay.example.com
password: StrongRedisPassw0rd
port: 6379
FEATURE_USER_INITIALIZE: true
FEATURE_USER_CREATION: false
SUPER_USERS:
- quayadmin
Start the Quay registry container by running the following commands:
sudo podman run -d -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.11
To list running containers, run the following commands:
$ sudo podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1f9e6943b7ec registry.redhat.io/rhel8/postgresql-16:latest run-postgresql 10 hours ago Up 10 hours 0.0.0.0:5432->5432/tcp postgresql-quay
2b1e65c3fe6f registry.redhat.io/rhel8/redis-6:latest run-redis 10 hours ago Up 10 hours 0.0.0.0:6379->6379/tcp redis-quay
cc0dcad6ad08 registry.redhat.io/quay/quay-rhel8:v3.11 registry 8 seconds ago Up 8 seconds 0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp quay
You can check container startup logs using:
sudo podman logs quay
Step 6: Using Red Hat Quay
Open all required ports in the firewall:
sudo firewall-cmd --permanent --add-service={http,https}
sudo firewall-cmd --reload
Generate a new user with a username, password, email, and access token by running the following curl
commands:
curl -X POST -k http://quay.example.com/api/v1/user/initialize --header 'Content-Type: application/json' \
--data '{ "username": "quayadmin", "password":"Str0ngAdminPassw0rd", "email": "[email protected]", "access_token": true}'
Where:
- quay.example.com is the Quay server hostname
- quayadmin is the username
- Str0ngAdminPassw0rd is the admin user password
- [email protected] is the email address of the admin user
If it is successful, you will get an object with the username, email, and encrypted password. See example:
{"access_token":"FAPE5IUZUV607OSJY4OKA2MUD2Z6IZQ1C5GNBCOI","email":"[email protected]","encrypted_password":"cGzgFGyVT0zPuvhUEMha/bk+Kd7JUT7+JJ3lw6R1Ps4UF5jONA4lOcMjqocIkqUtk3CFf70m/ywe0BGEgQPFsw==","username":"quayadmin"}
Open your web browser and access Red Hat Quay registry user interface at http://quay.example.com. Replace the domain with your correct server hostname as mapped in DNS server or /etc/hosts
file. The same FQDN should be configured in config.yaml
file.

Login with the username created and its password.

You can create a new organization for your repositories under “Create New Organization“

Give organization a name and hit “Create Organization“

Within the organization you can now create repositories using “Create New Repository” button.

Give the repository a name and select if private or public. You can also initialize it with Dockerfile or link with Git repository.

Your repository is ready for use.

Visit official Quay documentation pages for how to use it.
More reading,
- Install and Use Docker Registry on Fedora
- How to Setup Docker Private Registry on Ubuntu
- Install and Configure Docker Registry on Rocky / AlmaLinux