Last updated: 29 Mar 2023

Get started on GOV.UK

This getting started guide is for new technical staff (for example developers, technical architects) working on GOV.UK in GDS. Please note this guidance is only for the GOV.UK programme of GDS, it is not for Digital Identity, Digital Services Platforms or any other part of GDS.

Ask your tech lead to take you through the overview slides if they have not already done so.

If you’re having trouble with this guide, you can ask your colleagues on the #govuk-developers Slack channel or using email.

Before you start

You must have a laptop with full admin access. To check if you have full admin access, run a sudo command in your command line. For example, sudo ls.

If you do not have full admin access to your laptop, ask your line manager to ask IT to provide you with a developer build on your laptop.

Once you have full admin access on your laptop, run the following in your command line to install the Xcode command line tool:

xcode-select --install

1. Install the Homebrew package manager

Run the following in your command line to install the Homebrew package manager:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

This command works for macOS or Linux.

2. Generate a SSH key

If you have a YubiKey

If you have a YubiKey, you will use gpg-agent in place of ssh-agent, which requires a GPG key to have been generated.

1. Create a GPG key as per the Create a GPG Key documentation.

2. Add the following to the ~/.gnupg/gpg-agent.conf file:

   enable-ssh-support
   pinentry-program /usr/local/bin/pinentry-mac
   default-cache-ttl 60
   max-cache-ttl 120

1. Add the following to your ~/.zprofile file:

   export GPG_TTY=$(tty)
   export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
   gpgconf --launch gpg-agent

1. Run killall gpg-agent to stop any running gpg-agent processes.

2. Run ssh-add -L. This will output your public SSH key, which should end cardno:000000000000 (indicating it is from a YubiKey).

If you do not have a YubiKey

1. Generate a new SSH key for your laptop and add it to the ssh-agent for your GitHub account.

2. Add the following code into your .zshrc, ~/.bash_profile, or equivalent so that it is persistent between restarts:

   $ /usr/bin/ssh-add -K <YOUR-PRIVATE-KEY>

3. Set up your GitHub account

1. Set up a GitHub account. You can use your existing personal account.
2. Associate your GitHub account with your GDS email address, this can be in addition to your personal email address.

3. Ask a developer on your team who has production access (e.g. your tech lead) to add your GitHub username to the user monitoring system.

   If no other developers on your team are available, ask in the Technical 2nd Line Slack channel for someone to add you.

4. Email govuk-github-owners@digital.cabinet-office.gov.uk to request to be added to the alphagov organisation and the GOV.UK team to get access to repos and CI environment, add your tech lead a CC of the email. Please explain in the email which team you are working on and in what role; include a link to the pull request created in the previous step.

   Once this request has been actioned you’ll receive an email from GitHub, select Accept in the email.

5. Add the SSH key to your GitHub account.

6. Test that the SSH key works by running ssh -T git@github.com.

7. Add your name and email to your git commits. For example:

   $ git config --global user.email "friendly.giraffe@digital.cabinet-office.gov.uk"
   $ git config --global user.name "Friendly Giraffe"
   

4. Install GDS command line tools

On GOV.UK we use the following command-line tools for AWS and SSH access:

• govuk-connect
• gds-cli

1. To install these command line tools, run the following in the command line:

   brew tap alphagov/gds
   brew install gds-cli govuk-connect
   brew install --cask aws-vault
   

   The GDS CLI repository is private, so you must first set up your GitHub account.

2. Test that both tools work by running gds --help and gds govuk connect --help.

   If you see a fatal: no such path in the working tree error, that’s because you’re using ZSH, which has gds set up as a Git alias. To solve this, you can either:

   • remove that alias by adding unalias gds to your ~/.zshrc
   • use gds-cli instead of gds for all the relevant commands

3. Configure the GDS CLI by running:

   gds config email <FIRSTNAME>.<LASTNAME>@digital.cabinet-office.gov.uk
   

4. Run gds config yubikey false if you use your phone as an Multi-Factor Authentication (MFA) device.

   Run gds config yubikey true if you use a Yubikey.

5. Connect to the GDS VPN

If you’re outside of the office or on GovWiFi, you must connect to the GDS VPN to access to our infrastructure and internal services.

 For GDS issued MacBooks

Follow the GDS guidance on how to sign into the GDS VPN using Google credentials.

 For Bring Your Own Devices (BYOD)

Follow the VPN guide for Bring Your Own Devices (BYOD)

6. Set up GOV.UK Docker

We use a govuk-docker Docker environment for local development.

To set up GOV.UK Docker, see the installation instructions in the govuk-docker GitHub repo.

You can also try developing outside of Docker, using tools like rbenv directly. This approach generally works for frontend apps but not for other apps with databases, etc., and is not officially supported.

7. Get SSH access to integration

If you are a frontend developer you do not need to complete this step as part of your initial setup.

Get access

Ask a developer with production access on your team (e.g. your tech lead) to add your SSH username (firstnamelastname) to the list of GOV.UK tech users in the user monitoring system.

Create a user to SSH into integration

User accounts in our integration environments are managed in the govuk-puppet repository.

1. Run the following command to create a govuk folder in your home directory and clone the govuk-puppet GitHub repo:

   mkdir ~/govuk
   cd ~/govuk
   git clone git@github.com:alphagov/govuk-puppet.git
   

2. Add your SSH key which you created in step 2.

If you do not have a YubiKey, run more ~/.ssh/id_ed25519.pub to retrieve your public key. The key should begin with ssh-ed25519 AAA and end with == <WORK EMAIL>. If you have an existing RSA public key you could add that instead, although ed25519 keys are preferable. An RSA public key will start with ssh-rsa AAA. You may need to manually add the email address to the end of your key.

If you have a YubiKey, run ssh-add -L to retrieve the key from your device. The key should end with cardno:000000000000.

1. Create a user manifest file at ~/govuk/govuk-puppet/modules/users/manifests/<FIRSTNAMELASTNAME>.pp with the following code:

   # Creates the <FIRSTNAMELASTNAME> user
   class users::<FIRSTNAMELASTNAME> {
     govuk_user { '<FIRSTNAMELASTNAME>':
       fullname => 'FIRSTNAME LASTNAME',
       email    => 'WORK EMAIL',
       ssh_key  => '<SSH-PUBLIC-KEY-VALUE>',
     }
   }
   

   Enter your information and SSH public key value into the file. For example:

   # Creates the johnsmith user
   class users::<johnsmith> {
     govuk_user { '<johnsmith>':
       fullname => 'John Smith',
       email    => 'john.smith@digital.cabinet-office.gov.uk',
       ssh_key  => '<SSH-PUBLIC-KEY-VALUE>',
     }
   }
   

2. Add the name of your user manifest file (<FIRSTNAMELASTNAME>.pp) into the list of users::usernames in hieradata_aws/integration.yaml.

3. Create a pull request with these changes and ask a developer in your team to review it.

   Once the pull request has been reviewed, you can merge it and the pull request will automatically deploy to the integration environment.

Access remote environments and server

Once your pull request with your user manifest file is merged and deployed, you should test your SSH access to remote environments and servers.

If you are outside of the office or on GovWiFi, you must first connect to the GDS VPN.

Test your SSH access by running:

gds govuk connect --environment integration ssh backend

If you see an error Permission denied, check the message shown later, similar to: The SSH username used was: jsmith - if this is not the user you specified in the puppet config above, you need to specify a username:

USER=jaysmith gds govuk connect --environment integration ssh backend

(or you can export USER=jaysmith separately to set it for a shell session)

If you see an error similar to no matching host key type found. Their offer: ssh-rsa,ssh-dss you will have to change your ssh configuration - this is an issue with OSX Ventura (and possibly other operating systems) - see this StackOverflow issue

You need to add the following into your ssh config (e.g. ~/.ssh/config):

Host *
  HostkeyAlgorithms +ssh-rsa
  PubkeyAcceptedAlgorithms +ssh-rsa

Note this may happen even if you don’t use an rsa ssh private key - it is caused by the host key which is defined by the server you connect to, not your user key which you have defined.

Running a console

Once you have SSH access into a remote environment or server, you can also open a Rails app console for a particular application so you can run commands.

For example, to open a console for GOV.UK Publisher, run the following on a backend machine:

$ govuk_app_console publisher

As a shortcut, to remove the need to look up the machine class for an application, you can use the following without SSHing first:

gds govuk connect --environment integration app-console publisher

8. Get AWS access

If you are a frontend developer you do not need to complete this step as part of your initial setup.

GDS maintains a central account for AWS access.

You must have access to this GDS account to work with govuk-aws and govuk-aws-data.

The notes below are a summary - the definitive guide lives on the reliability engineering site.

Request access to the GDS AWS account

You request access to the GDS AWS account through the Request an AWS account form.

Select Request user access to request access to the GDS AWS account and complete the form.

After submitting the form, you should receive an email to say your account creation is in progress, and later another email saying the work has been completed.

Sign in to AWS

To sign in, go to the gds-users AWS console, and enter:

• gds-users in Account ID or alias
• your @digital.cabinet-office.gov.uk email address in Username
• your AWS account password in Password

Set up Multi-Factor Authentication

You must set up Multi-Factor Authentication (MFA) to access AWS.

You may add up to 8 MFA devices. However, note that MFA device names must be prefixed with your IAM username (usually your email address), otherwise you will receive a permissions error.

How you set up MFA depends on whether you have a GDS-issued Yubikey or not.

If you do not have a Yubikey

Use the following instructions to set up your MFA device.

1. Sign in to the gds-users AWS console.
2. Select the IAM service.
3. Select Users in the left hand menu and enter your name.
4. Select the link for your email address.
5. Select the Security credentials tab.
6. Select Manage, which is next to Assigned MFA device.
7. Specify your email address as the MFA device name
8. Follow the instructions to set up your MFA device.

If you have a Yubikey

1. Download the Yubico Authenticator app to your computer (or mobile device, if your Yubikey supports NFC).
2. Sign in to the gds-users AWS console.
3. Select the IAM service.
4. Select Users in the left hand menu and enter your name.
5. Select the link for your email address.
6. Select the Security credentials tab.
7. Select Manage, which is next to Assigned MFA device.
8. Specify your email address as the MFA device name
9. When asked to scan the QR code with your mobile device, open the Yubico Authenticator app and use that to scan the QR code. The MFA code will now be present on your Yubikey.
10. Configure gds-cli to use the YubiKey:

gds config yubikey true

Generate a pair of access keys

You must generate an AWS access key ID and secret access key to be able to perform operations with AWS on the command line.

1. Sign in to the gds-users AWS console.
2. Select your email address in the top right of the screen.
3. Select My Security Credentials.
4. Select Create access key.
5. Make a note of your AWS access key ID and secret access key for when you access AWS for the first time.

Get access to integration infrastructure

You must get access to the integration infrastructure so you can deploy to integration.

To get access, you must add your email address to the list of role_user_user_arns users in the govuk-aws-data GitHub repo.

Open a pull request to add the following code to the role_user_user_arns section in the infra-security/integration/common.tfvars file in the govuk-aws-data repo.

arn:aws:iam::<account-ID>:user/<firstname.lastname>@digital.cabinet-office.gov.uk

Use the same <account-ID> as other entries in the role_user_user_arns section.

See this example pull request for more information.

After your pull request has been merged, someone with production access will need to deploy the infra-security project to integration, by assuming the govuk-integration-admin role. See Deploy Terraform to find out how to deploy infrastructure changes. The stackname is govuk and the project is infra-security.

See the AWS IAM users documentation for more information.

9. Access AWS for the first time

If you are a frontend developer you do not need to complete this step as part of your initial setup.

1. Open the GDS CLI and run gds aws govuk-integration-readonly -l to open the AWS console in your web browser.
2. In the GDS CLI, enter your AWS access key ID and secret access key.

3. Enter your MFA token in the command line.

   Here is an example of the output you’ll see:

   $ gds aws govuk-integration-readonly -l
   Welcome to the GDS CLI! We will now store your AWS credentials in the keychain using aws-vault.
   Enter Access Key ID: <YOUR-ACCESS-KEY-ID>
   Enter Secret Access Key: <YOUR-SECRET-ACCESS-KEY>
   Added credentials to profile "gds-users" in vault
   Successfully initialised gds-cli
   Enter token for arn:aws:iam::123456789012:mfa/firstname.lastname@digital.cabinet-office.gov.uk: 123456
   

4. When prompted, save credentials to your Mac’s keychain as aws-vault and set a password for the keychain. Save that password somewhere safe, for example in a password manager.

If you have a GDS-issued Yubikey, you can run gds config yubikey true in the GDS CLI to set GDS CLI to automatically pull the MFA code from your Yubikey.

You have completed the get started process. You can now use gds aws to run generic aws CLI commands by prefixing them with gds aws <role>. For example:

$ gds aws govuk-integration-readonly aws s3 ls

Reset your AWS vault password

If you forget your aws-vault password, you must reset that password.

1. Delete the aws-vault keychain by running rm ~/Library/Keychains/aws-vault.keychain-db in the command line.
2. Re-initialise the gds-cli by opening ~/.gds/config.yml and changing initialised: true to initialised: false.

10. Set up tools to use the GOV.UK Kubernetes platform

Follow the instructions for setting up tools to use the GOV.UK Kubernetes platform.

11. Get a Signon account for integration

Signon is the application used to control access to the GOV.UK Publishing applications.

Ask another developer to create an account for the integration Signon, at ‘Superadmin’ level with permission to access the applications that your team are likely to work on.

12. Get access to the Release app

Release is the application we use to track deployments, work out which branch/tag is deployed to each environment and link to Jenkins to deploy code.

Ask someone with production access (e.g. your tech lead or buddy) to create an account for the production Signon, at ‘Normal’ level with access to the ‘Release’ app only. No permissions should be given for other applications, until production access is granted.

Supporting information

Now you have completed the get started process, you should look at the following supporting information:

• the architectural deep dive of GOV.UK
• how GDS uses Docker

More in the Learning GOV.UK section

Learn

• Dictionary of concepts on GOV.UK
• How to be a good buddy
• Responsibilities of a Tech Lead
• Where to find what documentation

How to...

• Ask for help
• Learn how GOV.UK works