Introduction

This is a simple UK postcode checking app that enables you to specify your own supported postcodes paired with LSOAs (Lower Layer Super Output Area) they belong to. Upon entering a postcode, the application will first check against the supported postcodes list and then fallback onto Postcodes.io service that offers postcode lookups and returns detailed postcode info, including postcode's LSOA, that is then checked against supported LSOAs list.

Installing the app

You'll need a Ruby environment installed (version and gemset are specified for RVM users). You'll also need Docker engine and docker-compose tool installed as the app uses PostgreSQL database, and instead of installing and setting up database, a docker image is used.

Step by step for fresh Ubuntu installations:

Installing RVM

sudo apt-add-repository -y ppa:rael-gc/rvm
sudo apt-get update
sudo apt-get install rvm
source /etc/profile.d/rvm.sh

Install git if not already installed and clone the repository:

sudo apt-get install git
git clone https://github.com/Pinelynx/postcode-checker.git

Change directory to project root

cd postcode-checker

If Ruby version 3.0.0 is not installed you'll get the following message:

Required ruby-3.0.0 is not installed.
To install do: 'rvm install "ruby-3.0.0"'

Install the needed version by using the above displayed command:

rvm install "ruby-3.0.0"

You might run into some issues while installing the ruby version, those are tied to permissions and shell not recognizing rvm command properly. Fixing them depends on the OS, in my case following and relog worked:

echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" >> ~/.bashrc

If the correct version is installed you'll get the message that postcode-checker gemset is installed, which you can easily later remove when no longer needed:

rvm gemset delete postcode-checker

Installing gems

Install the necessary gems by running:

bundle install

There is a chance installing the gem will fail as pg gem dependencies might be missing, you can get them by using:

sudo apt-get install libpq-dev

Installing Docker engine

Next is installing Docker engine (see instructions):

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \
  "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

And then, to see if it works:

sudo docker run hello-world

Next and final prerequisite is installing the docker-compose tool (see instructions):

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

And finally, to see if it works:

docker-compose --version

After that, from the project root directory, you should be able to run:

sudo docker-compose up -d

And the database service should now be up. To shut it down, use:

sudo docker-compose down

Running the app

Make a copy of .env.example file and name it .env, from it environment variables will be read:

cp .env.example .env

Get the database ready:

rails db:create
rails db:migrate
rails db:seed
rails db:test:prepare

Run all the spec and rubocop:

rspec
rubocop

And finally, run the application:

rails s

Postcode checking form is available both on root path and /check_postcode path

Application is preseeded with supported LSOAs:

• Southwark
• Lambeth
• Custom

And also with supported postcodes tied to "Custom" LSOA:

• SH24 1AA
• SH24 1AB

TL;DR: if you have everything set up

git clone https://github.com/Pinelynx/postcode-checker.git
cd postcode-checker
cp .env.example .env
sudo docker-compose up -d
rails db:migrate
rails db:seed
rails db:test:prepare
rspec
rubocop
rails s
sudo docker-compose down