From c518d106e472609217ad07a3237a71572d129768 Mon Sep 17 00:00:00 2001 From: Justin W. Flory Date: Mar 12 2020 20:09:19 +0000 Subject: docs: Convert Badges sysadmin SOP into Badges docs page This commit moves the Fedora Infra Docs SOP originally written in ReStructuredText into an AsciiDoc file in the Badges docs site: https://docs.pagure.org/infra-docs/sysadmin-guide/sops/badges.html Once this is merged into fedora-badges.git, I will follow up with a PR to the infra-docs.git repository to point to the new home of the SOP so there are not multiple sources of truth published at the same time. Also I tested all of the internal links and validated that they work. Signed-off-by: Justin W. Flory --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9b0e2fa..aeb98c7 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,2 +1,3 @@ -* xref:design-badges.adoc[How to design a Fedora Badge] * xref:join.adoc[Join Badges community] +* xref:design-badges.adoc[How to design Fedora Badges] +* xref:push-badges.adoc[How to push Fedora Badges] diff --git a/modules/ROOT/pages/push-badges.adoc b/modules/ROOT/pages/push-badges.adoc new file mode 100644 index 0000000..5787006 --- /dev/null +++ b/modules/ROOT/pages/push-badges.adoc @@ -0,0 +1,283 @@ += How to push Fedora Badges +:toc: + +== Architecture + +The badge-awarding back-end daemon, https://github.com/fedora-infra/fedbadges[fedbadges], wakes up when it receives a http://fedmsg.com/en/stable/[fedmsg] event. +It compares that message and the history in https://github.com/fedora-infra/datanommer[datanommer] against a series of rules. +If a contributor matches the criteria described in one of those rules, then they are awarded a badge. + +The front-end is a web application called https://github.com/fedora-infra/tahrir[Tahrir]. +It mostly is just an interface for users to look at their badges. +However, it also has an admin interface for manually adding new badges, awarding badges, and creating "invitations" (QR codes) for badges. + +The badge-awarding back-end daemon, https://github.com/fedora-infra/fedbadges[fedbadges], runs on the `badges-backend01` node. +The process is `fedmsg-hub` and logs are in `/var/log/fedmsg/fedmsg-hub.log`. + +The front-end runs under `apache/mod_wsgi` on `badges-web0{1,2}` nodes. + +=== Upstream documentation + +* For a detailed description of how the fedbadges daemon works, see the https://github.com/fedora-infra/fedbadges/blob/develop/README.rst[fedbadges README]. +* For a diagram of the interacting pieces in the Fedora Badges system, see the https://github.com/fedora-infra/fedbadges/blob/develop/diagrams/[fedbadges diagrams]. + + +== Sysadmin process: How to push a Badge + +Pushing badges consists of two operations: + +. Push badge assets (`.png`, `.svg`, `.yaml`) to https://pagure.io/fedora-badges[fedora-badges] repository +. Add badge to https://badges.fedoraproject.org/[badges.fedoraproject.org] + +Anyone with write permissions to https://pagure.io/fedora-badges[fedora-badges] can push badges. +Pull requests can also be used. +Only members of the `sysadmin-badges` FAS group _and_ xref:add-tahrir-admins[admins of the web interface] can add badges. + +Badge artists and badge developers should push design assets (`png` and `svg` art) and rules (`yaml`) to the https://pagure.io/fedora-badges[fedora-badges] repository. + +=== Preparing to create a badge + +Once a badge is approved by the Design Team and has the https://pagure.io/fedora-badges/issues?status=Open&tags=ready+to+push[ready to push] tag, they are ready to be pushed. +Follow this checklist to push a new badge: + +. Ensure artwork is *approved* by Design Team +. Ensure name and description of badge are clear +. Ensure one of these requirements is met: +** _Manually awarded badges_: What FAS accounts receive permissions to award badge +** _Awarded via fedmsg rule_: YAML file with rules is present + +If you are confused or something is missing, comment on the issue and remove the *ready to push* tag. + +=== Add badge assets to Pagure + +. Download artwork and rule file (if applicable): +** Double-check the artwork is actually the final version from ticket +** Open / view both art files to check they are not corrupt (in the past, corrupt images were accidentally pushed) +. Give both art and rule files the *same name*, place into https://pagure.io/fedora-badges/blob/master/f/pngs[pngs/], https://pagure.io/fedora-badges/blob/master/f/svgs[svg/], https://pagure.io/fedora-badges/blob/master/f/rules[rules/] directories +. _On request only_: Generate a STL file for 3D-printing a badge: +** Change directories into `bin/` and run `export.sh`. + This creates a STL file for the badge and moves it to the correct place. +** Check the `README` file in `bin/` for more info about the script. +. Commit all files and push to https://pagure.io/fedora-badges[fedora-badges] (or make a PR) + +Make sure files have a reasonable name (e.g. `all-lowercase-dashes-only.png`). +Some types of badges follow a naming convention, like FAS group membership badges (i.e. `fas-badge-name.png`) or Koji build badges (i.e. `koji-badge-name.png`). +Follow past precedent where possible. +Later, the file name is used for the file on the front-end server (e.g. `https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png`). + +=== Push assets to back-end server via Ansible + +_Note_: All assets must be in the `master` branch of https://pagure.io/fedora-badges[fedora-badges] before proceeding. +You must also be a member of `sysadmin-badges` in FAS for this to work. + +Next, you need to move all assets from the Pagure repository to the back-end server. +This is done via an https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/playbooks/manual/push-badges.yml[Ansible playbook] from the `batcave` server. +Follow these steps to push the assets to production. + +. SSH into `batcave01.phx2.fedoraproject.org` +. Run the playbook: `sudo rbac-playbook manual/push-badges.yml` +. Enter FAS password and https://docs.pagure.org/infra-docs/sysadmin-guide/sops/2-factor.html[2FA token] +. Once finished, ensure badge is now publicly visible (i.e. `https://badges.fedoraproject.org/pngs/.png`) + +=== Add automatically-awarded badges + +_Note_: Pay close attention when following these steps. +It is easy to create a badge, but much harder to edit it later. +Double-check information is entered correctly in the YAML file on first go, or else you have to write SQL statements to fix it later. + +Automatically awarded badges are created by the YAML rule file. +Once the Ansible playbook finishes, the badge is created and placed in the https://badges.fedoraproject.org/explore/badges[badges index]. +The only part _not_ created automatically are tags (see xref:badge-metadata[Badge metadata] below for info about tags). +To add new tags, find the badge on https://badges.fedoraproject.org/[badges.fedoraproject.org]. +If you are logged in as an admin, there is a text field to enter in new tags. + +=== Add manually-awarded badges + +_Note_: Pay close attention when following these steps. +It is easy to create a badge, but much harder to edit it later. +Double-check information is entered correctly on first go, or else you have to write SQL statements to fix it later. + +Once the badge assets are pushed to the back-end, add the badge to the front-end, [.title-ref]#Tahrir#. +The front-end is hosted at https://badges.fedoraproject.org/[badges.fedoraproject.org]. +Follow these steps to add the badge in Tahrir. + +. Open _Admin_ interface on https://badges.fedoraproject.org/[badges.fedoraproject.org] +. Go to the _Add badge_ section. +. Enter in all information as provided in the badge ticket (see xref:badge-metadata[Badge metadata] below.) +. Double-check all entered information is *correct and accurate* +. Click _Create badge_ to create new badge + +The badge is now created. +You should be able to find in the https://badges.fedoraproject.org/explore/badges[badges index]. + +==== Grant authorizations + +Manually-awarded badges require authorized users to issue a badge. +You can do this at the bottom of the _Admin_ interface, near _Create Authorizations_. +Add the person to receive awarding privileges into the _Person Email_ field. +*This must be formatted as their fedoraproject.org email address* (e.g. FASuser [at] fedoraproject [dot] org). +For badge name, use the slug (or badge name) from the URL of the badge (e.g. for https://badges.fedoraproject.org/badge/commops-superstar[badges.fedoraproject.org/badge/commops-superstar], this is `commops-superstar`). + +To add multiple users, repeat this process for each user. + +[[badge-metadata]] +=== Badge metadata + +* *Name*: name of the badge – this determines URL of badge, so triple-check for typos +* *Image*: full link to the PNG (e.g. `https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png`) +* *Description*: badge description text (ensure there is _no_ hanging whitespace) +* *Criteria*: link to the issue in https://pagure.io/fedora-badges[fedora-badges] +* *Issuer*: keep the default +* *Tags*: comma-delimited list of tags: +** *Review other similar badges to ensure tags are correct.* + Some tags are special and function as categories. +** *Follow past precedent* for tags. + Avoid creating new tags if at all possible. +** Removing tags _is not_ easy. + Adding them later _is_ easy. + +==== Close out the ticket + +After pushing the badge, do some last checks to make sure the badge pushed correctly. +Make sure the page is viewable and double-check that it is categorized correctly in the https://badges.fedoraproject.org/explore/badges[badges index]. + +Return to the Pagure issue for the badge. +Post a link to the pushed badge. +If you granted authorizations, list the FAS usernames you granted authorizations to. +After commenting, closing the issue as *pushed*. + +Congratulations, you just pushed your very own Fedora Badge! + + +== How to manually award a badge + +To perform this, you must be in the `sysadmin-badges` FAS group. + +There is a script installed on `badges-backend01` in `/usr/local/bin/award-badge`. +It has help options that you can pull up with `award-badge -h`. +It takes a required `--user FAS_USERNAME` and a required `--badge BADGE_ID` option. +For example, the following invocation would award the "Associate Editor" badge to "ralph": + +[source,bash] +---- +sudo /usr/local/bin/award-badge --user ralph --badge associate-editor +---- + +The `BADGE_ID` for a badge can be found by visiting its page on the web UI. +That badge can be found at `https://badges.fedoraproject.org/badge/associate-editor`. + +The `award-badge` script and source code is managed by ansible.git. +The source code is in https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/badges/backend/files/award-badge[roles/badges/backend/files/award-badge]. + +Often enough, there is need for a workflow to batch award a badge to a number of people. +For instance, the _Keepin' Fedora Beautiful_ badge comes from a member of the Design Team posting a ticket with a list of FAS usernames (i.e. https://pagure.io/fedora-badges/issue/129[fedora-badges#129]). + +For cases, like that you can `wget` the file with the list of FAS usernames on `badges-backend01` and run something like: + +[source,bash] +---- +$ for i in $(cat keepingbeautiful-list ) ; do + sudo /usr/local/bin/award-badge --user $i --badge keepin-fedora-beautiful-f20; +done +---- + + +[[manually-revoke-badge]] +== How to manually revoke a badge or authorization + +You may revoke badge or badge authorizations in a similar fashion to the `award-badges` script. +You may chain the invocation of the `revoke-badge` or `revoke-authorization` script in the same manner as the `award-badges` script. + +.Revoking a badge: +[source,bash] +---- +sudo /usr/local/bin/revoke-badge --user ralph --badge associate-editor +---- + +.Revoking an authorization: +[source,bash] +---- +sudo /usr/local/bin/revoke-authorization --user ralph --badge associate-editor +---- + + +[[add-tahrir-admins]] +== How to add admins to Tahrir + +It would be nice if we could automatically grant admin access in the web interface to members of the `sysadmin-badges` FAS group. +We currently do not have this feature and must maintain the list of web UI admins separately. + +The configuration file for the badges front-end web app is managed by ansible.git. +The source code is in https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/badges/frontend/templates/tahrir.ini[roles/badges/frontend/templates/tahrir.ini]. + +In that file, find the `tahrir.admin` option. +It is a comma-separated list of email addresses that, when logged in, should be granted rights to access the admin panels at https://badges.fedoraproject.org/[badges.fedoraproject.org]. + +To add a new admin, add their `FAS_USERNAME@fedoraproject.org` email to that line, commit, and push. +Use Ansible to run the `groups/badges-web.yml` playbook to push the config change out to the web front-end nodes. + + +== How to create an invitation and QR code + +This is done through the admin panel of the web interface (although we can probably write a script for it to be used on the back-end node). + +Invitations / QR codes are typically created for Fedora events. +For instance at the Flock 2013 Fedora Contributors conference, we created a badge to award attendees. +We followed the procedure below to generate an invitation and a QR code. +Next, the QR code was distributed to conference organizers. +They added the QR code to the program brochure that each attendee was given. +Then, any attendee that scanned the code was redirected on their phone to the badges app, where they were awarded the badge. + +=== Create an invitation + +. Make sure you are an admin in the web interface and logged into https://badges.fedoraproject.org/[badges.fedoraproject.org] +. Click the _Admin_ link in the UI +. Under the _Invitations_ section, add this information: +** *Creation Date*: Optional. + It defaults to the current date. +** *Expiration Date*: Optional, but you probably want to specify one. + It defaults to 2 hours from the current time. + For instance, at the Flock 2013 conference, we set the expiration date at the end of the conference. + Anyone who tried to claim the badge with the QR code after that time would be denied, with the message _this invitation is expired_. +** *Badge ID*: "ID" of the badge you want to award. + See the xref:manually-revoke-badge[section above] for how to find a badge ID. +** *Person email*: Email of a person in the badges database. + In our case, use their Fedora email (e.g. `FAS_USERNAME@fedoraproject.org`). + +Now, the user you specified will have a link to the QR code and invite link on their profile page. +They can take initiative to distribute and share the badge as they wish. + + +== Useful scripts for manual work + +See `ansible/roles/badges/backend/files/` for the motherload. +These all get deployed to `/usr/local/bin/` on `badges-backend01` where you can login to execute them. + +*edit-badge*:: + Update the description and the criteria link for a badge. + Useful in the event you created it incorrectly, or if feedback from other stakeholders requires us to change something. +*award-badge*:: + Award a badge to a specific user. +*revoke-badge*:: + Removes a badge from a user to whom it has been awarded erroneously. + *Remember!* If you revoke a badge award from a user, you should also give them the `consolation-prize` badge as a token of apology. +*grant-authorization*:: + Grant authorization rights on a badge to a privileged user. + They can then create invitation links and QR codes for that badge as well as award it directly to other users from the web interface. +*revoke-authorization*:: + Revoke those authorization rights for a user on a given badge. + + +== Contact information + +Owner::: + Fedora Badges community + +Contact::: + #fedora-badges + +Servers::: + badges-web0*, badges-backend0* + +Purpose::: + Award "badges" to Fedora Contributors