#722 docs: Convert Badges sysadmin SOP into Badges docs page
Merged 2 years ago by jflory7. Opened 2 years ago by jflory7.

file modified
+2 -1
@@ -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]

@@ -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/<name>.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

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.

Screenshot from local preview

Metadata Update from @jflory7:
- Pull-request tagged with: type - docs

2 years ago

I did give the document a read and looks good to merge.

Pull-Request has been merged by jflory7

2 years ago