Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. On prem Red Hat Quay configuration overview

For on premise deployments of Red Hat Quay, the config.yaml file that is managed by the administrator is mounted into the container at startup and read by Red Hat Quay during initialization. The config.yaml file is not dynamically reloaded, meaning that any changes made to the file require restarting the registry container to take effect.

This chapter provides an overview of the following concepts:

  • The minimal required configuration fields.
  • How to edit and manage your configuration after deployment.

This section applies specifically to on premise Red Hat Quay deployment types. For information about configuring Red Hat Quay on OpenShift Container Platform, see "Red Hat Quay on OpenShift Container Platform configuration overview".

4.1. Required configuration fields

The following configuration fields are required for an on premise deployment of Red Hat Quay:

Field

Type

Description

AUTHENTICATION_TYPE
(Required)

String

The authentication engine to use for credential authentication.

Values:
One of Database, LDAP, JWT, Keystone, OIDC

Default: Database

BUILDLOGS_REDIS
(Required)

Object

Redis connection details for build logs caching.

.host
(Required)

String

The hostname at which Redis is accessible.

.password

String

The password to connect to the Redis instance.

DATABASE_SECRET_KEY
(Required)

String

Key used to encrypt sensitive fields within the database. This value should never be changed once set, otherwise all reliant fields, for example, repository mirror username and password configurations, are invalidated.
This value is set automatically by the Red Hat Quay Operator for Operator-based deployments. For standalone deployments, administrators can provide their own key using Open SSL or a similar tool. Key length should not exceed 63 characters.

DB_URI
(Required)

String

The URI for accessing the database, including any credentials.

DISTRIBUTED_STORAGE_CONFIG
(Required)

Object

Configuration for storage engine(s) to use in Red Hat Quay. Each key represents an unique identifier for a storage engine. The value consists of a tuple of (key, value) forming an object describing the storage engine parameters.

Default: []

SECRET_KEY
(Required)

String

Key used to encrypt the session cookie and the CSRF token needed for correct interpretation of the user session. The value should not be changed when set. Should be persistent across all Red Hat Quay instances. If not persistent across all instances, login failures and other errors related to session persistence might occur.

SERVER_HOSTNAME
(Required)

String

The URL at which Red Hat Quay is accessible, without the scheme.

SETUP_COMPLETE
(Required)

Boolean

This is an artifact left over from earlier versions of the software and currently it must be specified with a value of true.

USER_EVENTS_REDIS
(Required)

Object

Redis connection details for user event handling.

.host
(Required)

String

The hostname at which Redis is accessible.

.port
(Required)

Number

The port at which Redis is accessible.

.password

String

The password to connect to the Redis instance.

4.1.1. Minimal configuration file examples

This section provides two examples of a minimal configuration file: one example that uses local storage, and another example that uses cloud-based storage with Google Cloud Platform.

4.1.1.1. Minimal configuration using local storage

The following example shows a sample minimal configuration file that uses local storage for images.

Important

Only use local storage when deploying a registry for proof of concept purposes. It is not intended for production purposes. When using local storage, you must map the registry to a local directory to the datastorage path in the container when starting the registry. For more information, see Proof of Concept - Deploying Red Hat Quay

Local storage minimal configuration

Copy to Clipboard Toggle word wrap 
AUTHENTICATION_TYPE: Database
BUILDLOGS_REDIS:
    host: <quay-server.example.com>
    password: <password>
    port: <port>
DATABASE_SECRET_KEY: <example_database_secret_key>
DB_URI: postgresql://<username>:<password>@<registry_url>.com:<port>/quay
DISTRIBUTED_STORAGE_CONFIG:
  default:
    - LocalStorage
    - storage_path: /datastorage/registry
SECRET_KEY: <example_secret_key>
SERVER_HOSTNAME: <server_host_name>
SETUP_COMPLETE: true
USER_EVENTS_REDIS:
  host: <redis_events_url>
  password: <password>
  port: <port>

4.1.1.2. Minimal configuration using cloud-based storage

In most production environments, Red Hat Quay administrators use cloud or enterprise-grade storage backends provided by supported vendors. The following example shows you how to configure Red Hat Quay to use Google Cloud Platform for image storage. For a complete list of supported storage providers, see Image storage.

Note

When using a cloud or enterprise-grade storage backend, additional configuration, such as mapping the registry to a local directory, is not required.

Cloud storage minimal configuration

Copy to Clipboard Toggle word wrap 
AUTHENTICATION_TYPE: Database
BUILDLOGS_REDIS:
    host: <quay-server.example.com>
    password: <password>
    port: <port>
DATABASE_SECRET_KEY: <example_database_secret_key>
DB_URI: postgresql://<username>:<password>@<registry_url>.com:<port>/quay
DISTRIBUTED_STORAGE_CONFIG:
    default:
        - GoogleCloudStorage
        - access_key: <access_key>
          bucket_name: <bucket_name>
          secret_key: <secret_key>
          storage_path: /datastorage/registry
DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS: []
DISTRIBUTED_STORAGE_PREFERENCE:
    - default
SECRET_KEY: <example_secret_key>
SERVER_HOSTNAME: <server_host_name>
SETUP_COMPLETE: true
USER_EVENTS_REDIS:
  host: <redis_events_url>
  password: <password>
  port: <port>

4.2. Modifying your configuration file after deployment

After deploying a Red Hat Quay registry with an initial config.yaml file, Red Hat Quay administrators can update the configuration file to enable or disable features as needed. This flexibility allows administrators to tailor the registry to fit their specific environment needs, or to meet certain security policies.

Note

Because the config.yaml file is not dynamically reloaded, you must restart the Red Hat Quay container after making changes for them to take effect.

The following procedure shows you how to retrieve the config.yaml file from the quay-registry container, how to enable a new feature by adding that feature’s configuration field to the file, and how to restart the quay-registry container using Podman.

Prerequisites

  • You have deployed Red Hat Quay.
  • You are a registry administrator.

Procedure

  1. If you have access to the config.yaml file:

    1. Navigate to the directory that is storing the config.yaml file. For example:

      Copy to Clipboard Toggle word wrap 
      $ cd /home/<username>/<quay-deployment-directory>/config

    2. Make changes to the config.yaml file by adding a new feature flag. The following example enables the v2 UI:

      Copy to Clipboard Toggle word wrap 
      # ...
FEATURE_UI_V2: true
# ...
    3. Save the changes made to the config.yaml file.

    4. Restart the quay-registry pod by entering the following command:

      Copy to Clipboard Toggle word wrap 
      $ podman restart <container_id>

  2. If you do not have access to the config.yaml file and need to create a new file while keeping the same credentials:

    1. Retrieve the container ID of your quay-registry pod by entering the following command:

      Copy to Clipboard Toggle word wrap 
      $ podman ps

      Example output

      Copy to Clipboard Toggle word wrap 
      CONTAINER ID  IMAGE                                                                     COMMAND         CREATED       STATUS       PORTS                                                                       NAMES
5f2297ef53ff  registry.redhat.io/rhel8/postgresql-13:1-109                              run-postgresql  20 hours ago  Up 20 hours  0.0.0.0:5432->5432/tcp                                                      postgresql-quay
3b40fb83bead  registry.redhat.io/rhel8/redis-5:1                                        run-redis       20 hours ago  Up 20 hours  0.0.0.0:6379->6379/tcp                                                      redis
0b4b8fbfca6d  registry-proxy.engineering.redhat.com/rh-osbs/quay-quay-rhel8:v3.14.0-14  registry        20 hours ago  Up 20 hours  0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp, 7443/tcp, 9091/tcp, 55443/tcp  quay

    2. Copy the config.yaml file from the quay-registry pod to a directory by entering the following command:

      Copy to Clipboard Toggle word wrap 
      $ podman cp <container_id>:/quay-registry/conf/stack/config.yaml ./config.yaml

    3. Make changes to the config.yaml file by adding a new feature flag. The following example sets the AUTHENTICATION_TYPE to LDAP

      Copy to Clipboard Toggle word wrap 
      # ...
AUTHENTICATION_TYPE: LDAP
# ...

    4. Re-deploy the registry, mounting the config.yaml file into the quay-registry configuration volume by entering the following command:

      Copy to Clipboard Toggle word wrap 
      $ sudo podman run -d --rm -p 80:8080 -p 443:8443 \
   --name=quay \
   -v /home/<username>/<quay-deployment-directory>/config:/conf/stack:Z \
   registry.redhat.io/quay/quay-rhel8:v3.14.0

4.3. Troubleshooting the configuration file

Failure to add all of the required configuration field, or to provide the proper information for some parameters, might result in the quay-registry container failing to deploy. Use the following procedure to view and troubleshoot a failed on premise deployment type.

Prerequisites

  • You have created a minimal configuration file.

Procedure

  • Attempt to deploy the quay-registry container by entering the following command. Note that this command uses the -it, which shows you debugging information:

    Copy to Clipboard Toggle word wrap 
    $ podman run -it --rm -p 80:8080 -p 443:8443 --name=quay -v /home/<username>/<quay-deployment-directory>/config:/conf/stack:Z    -v /home/<username>/<quay-deployment-directory>/storage:/datastorage:Z 33f1c3dc86be

    Example output

    Copy to Clipboard Toggle word wrap 
    ---
+------------------------+-------+--------+
| LDAP                   | -     | X      |
+------------------------+-------+--------+
| LDAP_ADMIN_DN is required      | X      |
+-----------------------------------------+
| LDAP_ADMIN_PSSWD is required   | X      |
+-----------------------------------------+
| . . . Connection refused       | X      |
+-----------------------------------------+
---

    In this example, the quay-registry container failed to deploy because improper LDAP credentials were provided.

Back to top
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

© 2025 Red Hat, Inc.