Teaching Vacancies

Teaching Vacancies is a free job-listing service from the Department for Education. Teachers can search and apply for jobs at schools or trusts in England, save jobs and set up job alerts.

This repository contains the source code and infrastructure definitions for the main Teaching Vacancies service, a Ruby on Rails application with PostgreSQL and Redis backing services.

Onboarding

Welcome to the team! 🐯

You should have been added to our Github team ahead of time, if not, remind your delivery manager or tech lead to do that and also complete the other onboarding steps!

Quick start

This project uses devcontainers to provide a seamless onboarding experience for developers and other team members.

You will need the following software installed on your system:

• Git
• Docker Desktop
  • You will need to start Docker before the process will work.
• Visual Studio Code

To get the application running:

• Clone the repository to a folder of your choice
• Ask another developer for a .env file, and place it in the root of the application folder (you can set up your AWS access to be able to do this yourself later)
• Open the folder in VS Code, and when prompted, choose "Reopen in container"
• The container will now build and execute first run tasks - this will take between 5 and 10 minutes depending on the performance of your computer. Wait for the terminal showing build tasks to display "Done. Press any key to close the terminal."

When the build has finished, you can run the application by clicking on "▶️ Start app" in the status bar, using the VS Code "Run task" option, or the Rails convention bin/dev script. This will start:

• The Rails application running on http://localhost:3000
• An asset build task each for Javascript and CSS
• Sidekiq for processing background jobs

Optional: Advanced custom setup (for developers)

The Docker-based devcontainer setup (see configuration) is our "gold standard" reference implementation of a local development environment. We highly recommend you use it, but you're of course free to work in whatever way makes you the most happy and productive.

This might involve running a container-based workflow using vanilla docker-compose (working inside the container using a command-line text editor, or outside the container in a GUI editor or IDE), running a Linux VM with a container engine for that extra bit of performance, or just using the container definitions as a guide to setting the app up locally without any Docker involvement at all.

Following convention, a bin/dev script is provided that uses Foreman to run all the tasks needed for the application.

• API Documentation
• API Keys
• Continuous delivery
• Deployments
• Docker
• Publishers - DSI Integration
• Jobseekers - GOV.UK One Login Integration
• Hosting
• Integrations with other job posting services
• Logging
• Onboarding
• Search
• Disaster Recovery
• Front-end

---

Additional setup

This section describes optional additional setup tasks once you have the application up and running. It is mainly relevant for developers and not strictly necessary to run the application.

AWS credentials, MFA, and role profiles

Once onboarded to AWS, you should finish setting up your account by following the steps described in the AWS roles and CLI tools documentation.

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

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

Data

If you use the devcontainer, the database will be created and seeded on first run using standard rails db:prepare. The seeds generate a number of fake vacancies, job applications, and users, as well as importing required data from a number of external services.

You shouldn't have to refresh the external data, but if you do need to, you can with the following tasks:

# Import all schools, trusts, and local authorities from DfE's Get Information About Schools
bundle exec rails gias:import_schools

# Import location polygon data from the Office for National Statistics
bundle exec rails ons:import_all

If ever you want to start over, you can delete and re-seed using:

bundle exec rails db:drop db:prepare

The SQLTools VS Code extension is installed and configured in the devcontainer by default and can be used to browse the database and run SQL queries. The psql tool is also installed, so you can use rails dbconsole or even just psql tvs_development.

Tests and linting

The Rails application uses RSpec and RuboCop for testing and linting, as well as Brakeman for security scanning and Slim-Lint to lint Slim templates.

# Run tests and linting
bundle exec rake

# Run tests only
bundle exec rspec

# Run linters only
bundle exec rails lint

The frontend Javascript code uses Jest and ESLint for testing and linting (using Airbnb rules), as well as Stylelint for SASS linting (with the default ruleset):

# Run tests and linting
yarn test

# Run tests only
yarn run js:test

# Generate a coverage report
yarn run js:test:coverage

# Run JS linter only
yarn run js:lint

# Run SASS linter only
yarn run sass:lint

RSpec parallel testing

The service include parallel_tests gem, that allows to split the RSpec test suite run accross multiple CPU cores.

Each group will run against a separate database. To set it up:

RAILS_ENV=test rails parallel:create

To run the test suite in parallel:

RAILS_ENV=test rake parallel:spec

or

RAILS_ENV=test rails parallel:spec

or using Spring binstub:

parallel_rspec

Visual regression testing

The visual layout and appearance of defined scenarios (pages and common content) can be tested using BackstopJS

This works by testing snapshot images in a branch or environment against accepted baseline/reference snapshot images. Tests are run across 3 viewports - mobile, tablet and desktop. Also if abtest variants are added to config/ab_test.yml then the corresponding page will be tested with each variant.

This is currently a tool for developers to test changes locally against the QA environment. Running the test suite will create and load a UI in the browser to report on and for you to compare visual changes.

Setup

Install the backstopjs library as a global dependency

npm install -g [email protected]

Add the following variables to your local .env file:

VISUAL_TEST_JOBSEEKER_USERNAME=xxx
VISUAL_TEST_JOBSEEKER_PASSWORD=xxx
VISUAL_TEST_PUBLISHER_USERNAME=xxx
VISUAL_TEST_PUBLISHER_PASSWORD=xxx

Usage

If you have never run tests before, ensure you have created an backstop/lib/.tmp folder for authentication tokens. (TODO could do with automating)

# Create reference snapshot images
yarn run visual:test:init

# Run test suite to compare your changes to reference snapshots
yarn run visual:test:run

# approve changes
yarn run visual:test:approve

This will approve changes to create new baseline snapshots and clear your file system of snapshots created by previous test suite runs.