Adds procedure to update superuser password when forgotten

api/master.adoc

@@ -1,4 +1,4 @@
-:_content-type: CONCEPT
+:_content-type: ASSEMBLY
 
 
 include::modules/attributes.adoc[]

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

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

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

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:

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.