SupportConsoleDevelopersStart a trialContact

Chapter 4. On-premise Red Hat Quay configuration overview

For on-premise Red Hat Quay deployments, you manage a config.yaml file that Red Hat Quay reads at container startup. You must restart the registry container after you change the file because Red Hat Quay does not reload configuration dynamically.

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
Copy link

The following configuration fields are required to start an on-premises Red Hat Quay deployment. You must include each field in your config.yaml file before the registry can start.

Table 4.1. Required configuration fields
FieldTypeDescription

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.2. Minimal configuration file examples
Copy link

You can use minimal config.yaml file examples to start an on-premises Red Hat Quay registry with local or cloud-based storage. These examples show only the required fields.

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.2.1. Minimal configuration using local storage
Copy link

A minimal config.yaml for on-premises Red Hat Quay uses local storage for images. Use this example only for proof of concept deployments, not production.

Important

Only use local storage when deploying a registry for proof of concept purposes. Local storage 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

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>

A minimal config.yaml for on-premises Red Hat Quay can use cloud-based object storage such as Google Cloud Platform. Use this pattern when you deploy Red Hat Quay with a supported enterprise storage backend.

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

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>

To update your on-premises Red Hat Quay configuration after deployment, you can edit the config.yaml file and restart the quay-registry container. You can retrieve the file from the container if you do not have direct access to it.

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: 

      $ 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: 

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

      $ 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: 

      $ podman ps

      Example output

      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: 

      $ 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 

      # ...
AUTHENTICATION_TYPE: LDAP
# ...

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

      $ 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.4. Troubleshooting the configuration file
Copy link

To identify configuration errors that prevent your on-premises Red Hat Quay registry from starting, you can deploy the quay-registry container interactively and review the validation output.

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-premises 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: 

    $ 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

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

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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

Legal Notice

Theme

© 2026 Red HatBack to top