Setup Red Hat Quay Registry on Linux using Podman

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