diff --git a/api/master.adoc b/api/master.adoc index 1761c7c84..d31f59ced 100644 --- a/api/master.adoc +++ b/api/master.adoc @@ -1,4 +1,4 @@ -:_content-type: CONCEPT +:_content-type: ASSEMBLY include::modules/attributes.adoc[] diff --git a/modules/config-preconfigure-automation.adoc b/modules/config-preconfigure-automation.adoc index 5546fb32b..5f7984e14 100644 --- a/modules/config-preconfigure-automation.adoc +++ b/modules/config-preconfigure-automation.adoc @@ -7,7 +7,7 @@ [id="allowing-the-api-to-create-first-user"] == Allowing the API to create the first user -To create the first user using the `/api/v1/user/initialize` API, set the `FEATURE_USER_INITIALIZE` parameter to `true`. Unlike all other registry API calls which require an OAuth token that is generated by an OAuth application in an existing organization, the API endpoint does not require authentication. +To create the first user using the `/api/v1/user/initialize` API, set the `FEATURE_USER_INITIALIZE` parameter to `true`. Unlike all other registry API calls which require an OAuth token that is generated by an OAuth application in an existing organization, the API endpoint does not require authentication. After you have deployed {productname}, you can use the API to create a user, for example, `quayadmin`, assuming that no other users have already been created. For more information see xref:using-the-api-to-create-first-user[Using the API to create the first user]. @@ -17,9 +17,9 @@ After you have deployed {productname}, you can use the API to create a user, for Set the config option `BROWSER_API_CALLS_XHR_ONLY` to `false` to allow general access to the {productname} registry API. [id="adding-super-user"] -== Adding a super user +== Adding a superuser -After deploying {productname}, you can create a user. We advise that the first user be given administrator privileges with full permissions. Full permissions can be configured in advance by using the `SUPER_USER` configuration object. For example: +After deploying {productname}, you can create a user. It is suggested that the first user be given administrator privileges with full permissions. Full permissions can be configured in advance by using the `SUPER_USER` configuration object. For example: [source,yaml] ---- @@ -34,7 +34,7 @@ SUPER_USERS: [id="restricting-user-creation"] == Restricting user creation -After you have configured a super user, you can restrict the ability to create new users to the super user group. Set the `FEATURE_USER_CREATION` to `false` to restrict user creation. For example: +After you have configured a super user, you can restrict the ability to create new users to the super user group. Set the `FEATURE_USER_CREATION` to `false` to restrict user creation. For example: [source,yaml] ---- @@ -50,7 +50,7 @@ FEATURE_USER_CREATION: false [id="enabling-new-functionality-38"] == Enabling new functionality -To use new {productname} 3.8 functionality, enable some or all of the following features: +To use new {productname} 3.8 functionality, enable some or all of the following features: [source,yaml] ---- @@ -59,17 +59,17 @@ FEATURE_UI_V2: true FEATURE_LISTEN_IP_VERSION: FEATURE_SUPERUSERS_FULL_ACCESS: true GLOBAL_READONLY_SUPER_USERS: - - + - FEATURE_RESTRICTED_USERS: true RESTRICTED_USERS_WHITELIST: - - + - ... ---- [id="enabling-new-functionality-37"] == Enabling new functionality -To use new {productname} 3.7 functionality, enable some or all of the following features: +To use new {productname} 3.7 functionality, enable some or all of the following features: [source,yaml] ---- @@ -85,7 +85,7 @@ DEFAULT_SYSTEM_REJECT_QUOTA_BYTES: 102400000 [id="suggested-configuration-for-automation"] == Suggested configuration for automation -The following `config.yaml` parameters are suggested for automation: +The following `config.yaml` parameters are suggested for automation: [source,yaml] ---- diff --git a/modules/first-user-api.adoc b/modules/first-user-api.adoc index 7174d368e..53396ce36 100644 --- a/modules/first-user-api.adoc +++ b/modules/first-user-api.adoc @@ -1,34 +1,85 @@ :_content-type: PROCEDURE [id="deploy-quay-api"] -= Using the API to deploy {productname} += Using the API to deploy {productname} -This section introduces using the API to deploy {productname}. +This section introduces using the API to deploy {productname}. -.Prerequisites +.Prerequisites * The config option `FEATURE_USER_INITIALIZE` must be set to `true`. -* No users can already exist in the database. +* No users can already exist in the database. For more information on pre-configuring your {productname} deployment, see the section xref:config-preconfigure-automation[Pre-configuring {productname} for automation] [id="using-the-api-to-create-first-user"] == Using the API to create the first user -Use the following procedure to create the first user in your {productname} organization. +Use the following procedure to create the first user in your {productname} organization. [NOTE] ==== -This procedure requests an OAuth token by specifying `"access_token": true`. +This procedure requests an OAuth token by specifying `"access_token": true`. ==== -* Using the `status.registryEndpoint` URL, invoke the `/api/v1/user/initialize` API, passing in the username, password and email address by entering the following command: +. As the root user, install `python39` by entering the following command: + [source,terminal] ---- -$ curl -X POST -k https://example-registry-quay-quay-enterprise.apps.docs.quayteam.org/api/v1/user/initialize --header 'Content-Type: application/json' --data '{ "username": "quayadmin", "password":"quaypass123", "email": "quayadmin@example.com", "access_token": true}' +$ sudo yum install python39 +---- + +. Upgrade the `pip` package manager for Python 3.9: ++ +[source,terminal] +---- +$ python3.9 -m pip install --upgrade pip +---- + +. Use the `pip` package manager to install the `bcrypt` package: ++ +[source,terminal] +---- +$ pip install bcrypt +---- + +. Generate a secure, hashed password using the `bcrypt` package in Python 3.9 by entering the following command: ++ +[source,terminal] +---- +$ python3.9 -c 'import bcrypt; print(bcrypt.hashpw(b"subquay12345", bcrypt.gensalt(12)).decode("utf-8"))' +---- + +. Open your {productname} configuration file and update the following configuration fields: ++ +[source,yaml] +---- +FEATURE_USER_INITIALIZE: true +SUPER_USERS: + - quayadmin +---- + +. Stop the {productname} service by entering the following command: ++ +[source,terminal] +---- +$ sudo podman stop quay +---- + +. Start the {productname} service by entering the following command: ++ +[source,terminal] +---- +$ sudo podman run -d -p 80:8080 -p 443:8443 --name=quay -v $QUAY/config:/conf/stack:Z -v $QUAY/storage:/datastorage:Z {productrepo}/{quayimage}:{productminv} +---- + +. Run the following `CURL` command to generate a new user with a username, password, email, and access token: ++ +[source,terminal] +---- +$ curl -X POST -k http://quay-server.example.com/api/v1/user/initialize --header 'Content-Type: application/json' --data '{ "username": "quayadmin", "password":"quaypass12345", "email": "quayadmin@example.com", "access_token": true}' ---- + -If successful, the command returns an object with the username, email, and encrypted password. For example: +If successful, the command returns an object with the username, email, and encrypted password. For example: + [source,yaml] ---- @@ -41,10 +92,24 @@ If a user already exists in the database, an error is returned: ---- {"message":"Cannot initialize user in a non-empty database"} ---- -+ -If your password is not at least eight characters or contains whitespace, an error is returned: ++ +If your password is not at least eight characters or contains whitespace, an error is returned: + [source,terminal] ---- {"message":"Failed to initialize user: Invalid password, password must be at least 8 characters and contain no whitespace."} +---- + +. Log in to your {productname} deployment by entering the following command: ++ +[source,terminal] +---- +$ sudo podman login -u quayadmin -p quaypass12345 http://quay-server.example.com --tls-verify=false +---- ++ +.Example output ++ +[source,terminal] +---- +Login Succeeded! ---- \ No newline at end of file diff --git a/modules/operator-config-ui-change.adoc b/modules/operator-config-ui-change.adoc index 37b594528..949b11ad3 100644 --- a/modules/operator-config-ui-change.adoc +++ b/modules/operator-config-ui-change.adoc @@ -1,24 +1,31 @@ -[[operator-config-ui-change]] +:_content-type: PROCEDURE +[id="operator-config-ui-change"] == Changing configuration -In this example of updating the configuration, a superuser is added via the config editor tool: +In the following example, you will update your configuration file by changing the default expiration period of deleted tags. -. Add an expiration period, for example `4w`, for the time machine functionality: +.Procedure + +. On the config editor, locate the *Time Machine* section. + +. Add an expiration period to the *Allowed expiration periods* box, for example, `4w`: + image:ui-time-machine-add.png[Add expiration period] -. Select `Validate Configuration Changes` to ensure that the changes are valid -. Apply the changes by pressing the `Reconfigure Quay` button: + +. Select *Validate Configuration Changes* to ensure that the changes are valid. + +. Apply the changes by pressing *Reconfigure Quay*: + image:config-editor-reconfigure.png[Reconfigure] -. The config tool notifies you that the change has been submitted to Quay: +After applying the changes, the config tool notifies you that the changes made have been submitted to your {productname} deployment: + image:config-editor-reconfigured.png[Reconfigured] [NOTE] ==== -Reconfiguring {productname} using the config tool UI can lead to the registry being unavailable for a short time, while the updated configuration is applied. +Reconfiguring {productname} using the config tool UI can lead to the registry being unavailable for a short time while the updated configuration is applied. ==== diff --git a/modules/proc_deploy_quay_add.adoc b/modules/proc_deploy_quay_add.adoc index a11eaaf79..ddbedb6ff 100644 --- a/modules/proc_deploy_quay_add.adoc +++ b/modules/proc_deploy_quay_add.adoc @@ -53,14 +53,14 @@ the startup process. ==== + [subs="verbatim,attributes"] -``` +---- # sudo podman run --restart=always -p 443:8443 -p 80:8080 \ --sysctl net.core.somaxconn=4096 \ --privileged=true \ -v /mnt/quay/config:/conf/stack:Z \ -v /mnt/quay/storage:/datastorage:Z \ -d {productrepo}/{quayimage}:{productminv} -``` +---- . **Open browser to UI**: Once the `Quay` container has started, go to your web browser and open the URL, to the node running the `Quay` container. @@ -105,12 +105,12 @@ that is currently stored in `/root/ca.crt`. If not, then remove the line that ad `/root/ca.crt` to the container: + [subs="verbatim,attributes"] -``` +---- $ sudo podman run -d --name mirroring-worker \ -v /mnt/quay/config:/conf/stack:Z \ -v /root/ca.crt:/etc/pki/ca-trust/source/anchors/ca.crt \ {productrepo}/{quayimage}:{productminv} repomirror -``` +---- . **Log into config tool**: Log into the {productname} Setup Web UI (config tool). . **Enable repository mirroring**: Scroll down the Repository Mirroring section and select the Enable Repository Mirroring check box, as shown here: diff --git a/modules/resetting-superuser-password-on-operator.adoc b/modules/resetting-superuser-password-on-operator.adoc new file mode 100644 index 000000000..290c165aa --- /dev/null +++ b/modules/resetting-superuser-password-on-operator.adoc @@ -0,0 +1,82 @@ +:_content-type: CONCEPT +[id="resetting-superuser-password-on-operator"] += Resetting superuser passwords on the {productname} Operator + +.Prerequisites + +* You have created a {productname} superuser. +* You have installed Python 3.9. +* You have installed the `pip` package manager for Python. +* You have installed the `bcrypt` package for `pip`. + +.Procedure + +. Log in to your {productname} deployment. + +. On the {ocp} UI, navigate to *Workloads* -> *Secrets*. + +. Select the namespace for your {productname} deployment, for example, `Project quay`. + +. Locate and store the PostgreSQL database credentials. + +. Generate a secure, hashed password using the `bcrypt` package in Python 3.9 by entering the following command: ++ +[source,terminal] +---- +$ python3.9 -c 'import bcrypt; print(bcrypt.hashpw(b"newpass1234", bcrypt.gensalt(12)).decode("utf-8"))' +---- ++ +.Example output ++ +[source,terminal] +---- +$2b$12$zoilcTG6XQeAoVuDuIZH0..UpvQEZcKh3V6puksQJaUQupHgJ4.4y +---- + +. On the CLI, log in to the database, for example: ++ +[source,terminal] +---- +$ oc rsh quayuser-quay-quay-database-669c8998f-v9qsl +---- + +. Enter the following command to open a connection to the `quay` PostgreSQL database server, specifying the database, username, and host address: ++ +[source,terminal] +---- +sh-4.4$ psql -U quayuser-quay-quay-database -d quayuser-quay-quay-database -W +---- + +. Enter the following command to connect to the default database for the current user: ++ +[source,terminal] +---- +quay=> \c +---- + +. Update the `password_hash` of the superuser admin who lost their password: ++ +[source,terminal] +---- +quay=> UPDATE public.user SET password_hash = '$2b$12$zoilcTG6XQeAoVuDuIZH0..UpvQEZcKh3V6puksQJaUQupHgJ4.4y' where username = 'quayadmin'; +---- + +. Enter the following to command to ensure that the `password_hash` has been updated: ++ +[source,terminal] +---- +quay=> select * from public.user; +---- ++ +.Example output ++ +[source,terminal] +---- +id | uuid | username | password_hash | email | verified | stripe_id | organization | robot | invoice_email | invalid_login_attempts | last_invalid_login |removed_tag_expiration_s | enabled | invoice_email_address | company | family_name | given_name | location | maximum_queued_builds_count | creation_date | last_accessed +----+--------------------------------------+-----------+--------------------------------------------------------------+-----------------------+--- +-------+-----------+--------------+-------+---------------+------------------------+----------------------------+--------------------------+------ +---+-----------------------+---------+-------------+------------+----------+-----------------------------+----------------------------+----------- +1 | 73f04ef6-19ba-41d3-b14d-f2f1eed94a4a | quayadmin | $2b$12$zoilcTG6XQeAoVuDuIZH0..UpvQEZcKh3V6puksQJaUQupHgJ4.4y | quayadmin@example.com | t | | f | f | f | 0 | 2023-02-23 07:54:39.116485 | 1209600 | t | | | | | | | 2023-02-23 07:54:39.116492 +---- + +. Navigate to your {productname} UI on {ocp} and log in using the new credentials. \ No newline at end of file diff --git a/modules/troubleshooting-forgotten-passwords.adoc b/modules/troubleshooting-forgotten-passwords.adoc new file mode 100644 index 000000000..3c13838fc --- /dev/null +++ b/modules/troubleshooting-forgotten-passwords.adoc @@ -0,0 +1,110 @@ +:_content-type: CONCEPT +[id="troubleshooting-forgotten-passwords"] += Troubleshooting forgotten superuser passwords on {productname} + +Use the following procedures to reset superuser passwords on {productname}. + +[id="resetting-superuser-password-on-standalone"] +== Resetting superuser passwords on {productname} standalone deployments + +Use the following procedure to reset a superuser's password. + +.Prerequisites + +* You have created a {productname} superuser. +* You have installed Python 3.9. +* You have installed the `pip` package manager for Python. +* You have installed the `bcrypt` package for `pip`. + +.Procedure + +. Generate a secure, hashed password using the `bcrypt` package in Python 3.9 by entering the following command: ++ +[source,terminal] +---- +$ python3.9 -c 'import bcrypt; print(bcrypt.hashpw(b"newpass1234", bcrypt.gensalt(12)).decode("utf-8"))' +---- ++ +.Example output ++ +[source,terminal] +---- +$2b$12$T8pkgtOoys3G5ut7FV1She6vXlYgU.6TeoGmbbAVQtN8X8ch4knKm +---- + +. Enter the following command to show the container ID of your {productname} container registry: ++ +[source,terminal] +---- +$ sudo podman ps -a +---- ++ +.Example output ++ +[source,terminal] +---- +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +70560beda7aa registry.redhat.io/rhel8/redis-5:1 run-redis 2 hours ago Up 2 hours ago 0.0.0.0:6379->6379/tcp redis +8012f4491d10 registry.redhat.io/quay/quay-rhel8:v3.8.2 registry 3 minutes ago Up 8 seconds ago 0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp quay +8b35b493ac05 registry.redhat.io/rhel8/postgresql-10:1 run-postgresql 39 seconds ago Up 39 seconds ago 0.0.0.0:5432->5432/tcp postgresql-quay +---- + +. Execute an interactive shell for the `postgresql` container image by entering the following command: ++ +[source,terminal] +---- +$ sudo podman exec -it 8b35b493ac05 /bin/bash +---- + +. Re-enter the `quay` PostgreSQL database server, specifying the database, username, and host address: ++ +[source,terminal] +---- +bash-4.4$ psql -d quay -U quayuser -h 192.168.1.28 -W +---- + +. Update the `password_hash` of the superuser admin who lost their password: ++ +[source,terminal] +---- +quay=> UPDATE public.user SET password_hash = '$2b$12$T8pkgtOoys3G5ut7FV1She6vXlYgU.6TeoGmbbAVQtN8X8ch4knKm' where username = 'quayadmin'; +---- ++ +.Example output ++ +[source,terminal] +---- +UPDATE 1 +---- + +. Enter the following to command to ensure that the `password_hash` has been updated: ++ +[source,terminal] +---- +quay=> select * from public.user; +---- ++ +.Example output ++ +[source,terminal] +---- +id | uuid | username | password_hash | email | verified | stripe_id | organization | robot | invoice_email | invalid_login_attempts | last_invalid_login |removed_tag_expiration_s | enabled | invoice_email_address | company | family_name | given_name | location | maximum_queued_builds_count | creation_date | last_accessed +----+--------------------------------------+-----------+--------------------------------------------------------------+-----------------------+--- +-------+-----------+--------------+-------+---------------+------------------------+----------------------------+--------------------------+------ +---+-----------------------+---------+-------------+------------+----------+-----------------------------+----------------------------+----------- +1 | 73f04ef6-19ba-41d3-b14d-f2f1eed94a4a | quayadmin | $2b$12$T8pkgtOoys3G5ut7FV1She6vXlYgU.6TeoGmbbAVQtN8X8ch4knKm | quayadmin@example.com | t | | f | f | f | 0 | 2023-02-23 07:54:39.116485 | 1209600 | t | | | | | | | 2023-02-23 07:54:39.116492 +---- + +. Log in to your {productname} deployment using the new password: ++ +[source,terminal] +---- +$ sudo podman login -u quayadmin -p newpass1234 http://quay-server.example.com --tls-verify=false +---- ++ +.Example output: ++ +[source,terminal] +---- +Login Succeeded! +---- diff --git a/troubleshooting_quay/master.adoc b/troubleshooting_quay/master.adoc index 5144397ad..ef759f38e 100644 --- a/troubleshooting_quay/master.adoc +++ b/troubleshooting_quay/master.adoc @@ -4,6 +4,22 @@ include::modules/attributes.adoc[] [id="troubleshooting-quay"] = Troubleshooting {productname} -Use the content in this guide to troubleshoot your {productname} registry. Topics covered here include: +Use the content in this guide to troubleshoot your {productname} registry on both standalone and Operator based deployments. -* Resetting a forgotten superuser password on {productname} Operator and standalone deployments +[id="troubleshooting-quay-standalone"] +== Troubleshooting {productname} standalone deployments + +Topics covered here include: + +* Resetting a forgotten superuser password on {productname} + +include::modules/troubleshooting-forgotten-passwords.adoc[leveloffset=+1] + +[id="troubleshooting-quay-operator"] +== Troubleshooting {productname} Operator deployments + +Topics covered here include: + +* Resetting a forgotten superuser password on {productname} + +include::modules/resetting-superuser-password-on-operator.adoc[leveloffset=+1] \ No newline at end of file