Developer Onboarding: lizpearl

[vickyszuchin]

Developer Onboarding

• Onboardee: abroddrick
• Onboarder: lizperl

Installation

There are several tools we use locally that you will need to have.

• Cloudfoundry CLI
  • If you are using Windows the cli will be under cf8 or cf7 depending on which version you install.
  • If you are using Windows, installation information can be found here
  • Alternatively, for Windows, consider using chocolately
• GPG if you are using GPG to sign commits.
  • Make sure you have gpg >2.1.7. Run gpg --version to check. If not, install gnupg
  • This may not work on DHS devices. Alternatively, you can use ssh keys instead.
• Docker Community Edition*
• Git*
• VSCode (our preferred editor)*
• Github Desktop* or the Github CLI*

The following tools are optional but recommended. For DHS devices, these can be requested through the DHS IT portal:

• Slack Desktop App**
• Python 3.10*
• NodeJS (latest version available)*
• Putty*
• Windows Subsystem for Linux*

* Must be requested through DHS IT portal on DHS devices

** Downloadable via DHS Software Center

Access

Steps for the onboardee

• Setup commit signing in Github and with git locally using either gpg or ssh.
• Create a cloud.gov account
• Email [email protected] (cc: Cameron) to add you to the CISA Github organization and .gov Team.
• Ensure you can login to your cloud.gov account via the CLI

cf login -a api.fr.cloud.gov  --sso

• Have an admin add you to cloud.gov org and set up your sandbox developer space. Ensure you can deploy to your sandbox space.
• Have an admin add you to our login.gov sandbox team (.gov Registrar) via the dashboard.

Note: As mentioned in the Login documentation, the sandbox Login account is different account from your regular, production Login account. If you have not created a Login account for the sandbox before, you will need to create a new account first.

Follow the .gov onboarding dev setup instructions. Confirm you successfully set up the following accounts:

• Identity sandbox accounts - 1 superuser access account and 1 analyst access account.
• Login.gov account to access stable

Optional

• Add yourself as a codeowner if desired. See the Developer readme for how to do this and what it does.

Steps for the onboarder

• Add the onboardee to cloud.gov org (cisa-dotgov)
• Setup a developer specific space for the new developer
• Add the onboardee to our login.gov sandbox team (.gov Registrar) via the dashboard

Documents to Review

• Team Onboarding
• Architecture Decision Records
• Contributing Policy

Setting up commit signing with GPG

Follow GitHub's instructions to generate a new GPG key (default configurations are okay) and add it to your GitHub GPG keys.

Configure your key locally:

git config --global commit.gpgsign true
git config --global user.signingkey <YOUR KEY>

Where your key is the thing you generated to run the command

gpg --armor --export <YOUR KEY>

when setting up your key in Github.

Now test commit signing is working by checking out a branch (yourname/test-commit-signing) and making some small change to a file. Commit the change (it should prompt you for your GPG credential) and push it to Github. Look on Github at your branch and ensure the commit is verified.

Troubleshooting GPG on MacOS

Note: if you are on a mac and not able to successfully create a signed commit, getting the following error:

error: gpg failed to sign the data
fatal: failed to write commit object

You may need to add these two lines to your shell's rc file (e.g. .bashrc or .zshrc)

GPG_TTY=$(tty)
export GPG_TTY

and then

source ~/.bashrc

or

source ~/.zshrc

Troubleshooting GPG on Windows

If GPG doesn't work out of the box with git for you:

• You can download the GPG binary directly.
• It may be helpful to use gpg4win.

From there, you should be able to access gpg through the terminal.

Additionally, consider a gpg key manager like Kleopatra if you run into issues with environment variables or with the gpg service not running on startup.

Setting up commit signing with SSH

Follow GitHub's instructions to generate a new SSH key and add it to your GitHub SSH keys as a signing key.

Configure your key locally:

git config --global gpg.format ssh
git config --global commit.gpgsign true
git config --global user.signingkey <YOUR_KEY_PATH>

Where <YOUR_KEY_PATH> is the path of your public key file. GitHub defaults this to ~/.ssh/id_ed25519.pub. If you named SSH public key a different name from the default, you may need to replace id_ed25519.pub with the name you gave your key.

Now test commit signing is working by checking out a branch (yourinitials/test-commit-signing) and making some small change to a file. Commit the change (it should prompt you for your key passphrase) and push it to Github. Look on Github at your branch and ensure the commit is verified.

Setting up developer sandbox

We have three types of environments: stable, staging, and sandbox. Stable (production)and staging (pre-prod) get deployed via tagged release, and developer sandboxes are given to get.gov developers to mess around in a production-like environment without disrupting stable or staging. Each sandbox is namespaced and will automatically be deployed too when the appropriate branch syntax is used for that space in an open pull request. There are several things you need to setup to make the sandbox work for a developer.

All automation for setting up a developer sandbox is documented in the scripts for creating a developer sandbox and removing a developer sandbox. A Cloud.gov organization administrator will have to perform the script in order to create the sandbox.

Known Issues

SSL Verification Failure

Some developers using Government Furnished Equipment (GFE) have problems using tools such as git and pip due to SSL verification failurse. This happens because GFE has a custom certificate chain installed, but these tools use their own certificate bundles. As a result, when they try to verify an ssl connection, they cannot and so the connection fails. To resolve this in pip you can use --use-feature=truststore to direct pip to use the local certificate store. If you are running into this issue when using git on windows, run git config --global http.sslbackend schannel.

If you are running into these issues in a docker container you will need to export the root certificate and pull it into the container. Ask another developer how to do this properly.

Puppeteer Download Error

When building the node image either individually or with docker compose, there may be an error caused by a node package call puppeteer. This can be resolved by adding ENV PUPPETEER_SKIP_DOWNLOAD=true to node.Dockerfile after the COPY command.

Checksum Error

There is an unresolved issue with python package installation that occurs after the above SSL Verification failure has been resolved. It often manifests as a checksum error, where the hash of a download .whl file (python package) does not match the expected value. This appears to be because pythonhosted.org is cutting off download connections to some devices for some packages (the behavior is somewhat inconsistent). We have outstanding issues with PyPA and DHS IT to fix this. In the meantime we have a workaround.

Developing Using Docker

While we have unresolved issues with certain devices, you can pull a pre-built docker image from matthewswspence/getgov-base that comes with all the needed packages installed. To do this, you will need to change the very first line in the main Dockerfile to FROM matthewswspence/getgov-base:latest. Note: this change will need to be reverted before any branch can be merged. Additionally, this will only resolve the checksum error, you will still need to resolve any other issues through the listed instructions. We are actively working to resolve this inconvenience.

[vickyszuchin]

Moving forward from sprint 54 to sprint 55.

[vickyszuchin]

Any "In progress" tickets from Sprint 55 will be moved to the current sprint (Sprint 56) at noon EST (10am MT/9am PST) on Day 1.