Teaching Vacancies

Setup

Welcome! 🎉 🎆 🐯

By now you should be onboarded.

The first thing to do is to install the required development tools. If you are on a Mac, this script will install Homebrew, Git, asdf-vm, Ruby, Bundler, Node.js, npm, Yarn, Postgres, Redis and other useful utilities.

Then, clone the project with SSH:

git clone git@github.com:DFE-Digital/teaching-vacancies.git

If you are on a new device, remember to generate a new SSH key.

Dependencies

Ruby
NodeJS
shared-mime-info (installed using Homebrew or other package manager of your choice, the mimemagic gem depends on this)

A tool like asdf-vm can help you install the required versions of Ruby and Node.js. Current versions that match production ones are specified in .tool-versions.

If asdf-vm is installed correctly, from the project repository you can just execute:

asdf install

If asdf install fails with the below message, and you are on a Mac, install GPG Suite.

You must install GnuPG to verify the authenticity of the downloaded archives before continuing with the install: https://www.gnupg.org/

Services

Make sure you have the following services configured and running on your development background:

If using Homebrew to install PostgreSQL, run brew services start postgresql in order to have launchd start PostgreSQL and restart whenever you log in.

ChromeDriver

To install

brew install --cask chromedriver

To update

brew upgrade --cask chromedriver

On macOS you might need to "un-quarantine" chromedriver too

which chromedriver
xattr -d com.apple.quarantine /path/to/chromedriver

Install dependencies

Install Ruby dependency libraries

bundle

Install the version of Bundler that created the lockfile if prompted to do so.

Install Javascript dependency libraries

yarn

AWS credentials, MFA, and role profiles

When onboarded, you will be provided with an AWS user. You can use it to access the AWS console at: https://teaching-vacancies.signin.aws.amazon.com/console.

Set up MFA and install command-line tools

Environment Variables

Some environment variables are stored in AWS Systems Manager Parameter Store, some are stored in the repository.

Secrets (eg: API keys) are stored in AWS Systems Manager Parameter Store in /teaching-vacancies/<env>/app/* and /teaching-vacancies/<env>/infra/* files.

Non-secrets (eg: public URLs or feature flags) are stored in the repository in terraform/workspace-variables/<env>_app_env.yml files.

Run the following command to fetch all the required environment variables for development and output to a shell environment file:

aws-vault exec ReadOnly -- make -s local print-env > .env

To run the command above you need AWS credentials.

Git secrets offers an easy way to defend against accidentally publishing these secrets.

Override variables for local development

For local development, you can use a dotenv-rails environment override:

create the file .env.local, with contents

DFE_SIGN_IN_REDIRECT_URL=http://localhost:3000/publishers/auth/dfe/callback
DOMAIN=localhost:3000
LOCKBOX_MASTER_KEY=0000000000000000000000000000000000000000000000000000000000000000

Set up the database

bundle exec rails db:create db:schema:load

/config/database.yml sets the default for DATABASE_URL to postgis://postgres@localhost:5432, which should work without any additional configuration on a Mac.

If you set up your local Postgres with a custom user and password, such as in Ubuntu 20.04, set this in .env.local:

DATABASE_URL=postgis://mylocaluser:mylocalpassword@localhost:5432

⚠ Note that the database URL has postgis as its adapter, not postgres!

Seed the database

To create a few vacancies in your database run:

bundle exec rails db:seed

Import data

ONS Location polygons

⏳ This might take a while, so brew some tea while you wait.

Run these rake tasks to populate your database with location polygons. These are required in some cases to search by location.

bundle exec rails ons:import_location_polygons

GIAS data (schools, trusts and local authorities)

⏳ This is optional, and takes a while.

To populate your environment with real school data, taken from GIAS:

bundle exec rails gias:import_schools

Run the server

bundle exec rails server

Look at that, you’re up and running! Visit http://localhost:3000 and you’re ready to go.

Use live reloading

Optionally, use live reloading with bin/webpack-dev-server to save time when developing front-end assets:

yarn run dev

Run the worker

bundle exec sidekiq -C config/sidekiq.yml

Run the tests

Ruby

This uses a standard RSpec and RuboCop stack. To run these together:

bundle exec rake

To run only RSpec:

bundle exec rspec

To run only RuboCop:

bundle exec rubocop

JavaScript

npm test

The full test suite including linting can be run as parallel tasks using the command:

yarn test

To run unit tests written using Jest:

yarn run js:test

To generate a coverage report of unit tests you can run:

yarn run js:test:coverage

Linting of Javascript files uses ESLint and the ruleset is extended using Airbnb rules which are widely acknowledged as a comprehensive ruleset for modern Javascript. To run Javascript linting:

yarn run js:lint

SASS

Linting of SASS files uses Stylelint default ruleset and can be run using:

yarn run sass:lint

Troubleshooting

I see Page Not Found when I log in and try to create a job listing.

Try seeding the database (quick) or importing the school data (slow) if you have not already. When your sign in account was created, it was assigned to a school via a URN, and you may not have a school in your database with the same URN.

Misc

Getting production-like data for local development

To get sanitised production-like data for local development, first log in to AWS with the ReadOnly role. To do so, follow the instructions here: AWS Login.

Once logged in, go to S3 > 530003481352-tv-db-backups > sanitised. Then click the checkbox next to the backup you want (the names of the backups will include dates) and click "Download".

Then, unzip the file and load it into your local database like so:

  psql tvs_development < <path to unzipped .sql backup file>

Integration between Jira and Github

The integration allows to see the status of development from within the jira issue. You can see the status of branches, commits and pull requests as well as navigate to them to show the detail in Github.

To enable this, the following formatting must be used:

Branch: Prefix with the issue id. Ex: TEVA-1155-test-jira-github-integration
Commit: Prefix with the issue id between square bracket. Ex: [TEVA-1155] Update Readme
Pull request: Prefix with the issue id between square bracket. If the branch was prefixed correctly, this should be automatically added for you. Ex: [TEVA-1155] Document Jira-Github integration

The branch, commit or pull request will then appear in the Development side panel within the issue.

felixclack / teaching-vacancies