/paapi

Planning Applications API

Primary LanguageRuby

Planning Applications API

A Rails API which will store planning application data.

Dependency Version
Ruby 3.2.2
Rails 7.0.6
Postgresql 14.2

Getting started

Clone the project

$ git@github.com:unboxed/planning-applications-api.git

Using Docker

We recommend using Docker Desktop to get setup quickly. If you'd prefer not to use Docker then you'll need to install Ruby (3.2+) and PostgreSQL (14+).

First Time Setup using Docker

Create the databases

$ docker-compose run --rm web rails db:setup

Start the services

$ docker-compose up

Once the services have started you can access it here.

Tests

You can run the full test suite using following command:

$ docker-compose run --rm web rake

Individual specs can be run using the following command:

$ docker-compose run --rm web rspec spec/models/planning_application_spec.rb

Debugging using binding.pry

  1. Initially we have installed pry-byebug to development and test group on our Gemfile
group :development, :test do
  # ..
  gem 'pry-byebug'
  # ..
end
  1. Our docker-compose.yml in the web container contains the following two line which this will allow shell on a running container:
web:
  ..
  ..
  tty: true
  stdin_open: true
  1. Add binding.pry to the desired place you want to have a look on your rails code:
def index
  binding.pry
end
  1. Run your docker app container and get the container id
$ docker-compose up web
  1. Open a separate terminal run docker ps and to get a list of active containers and get the container id:
$ docker ps

You will get something like that: (65f0b2c36363 is the container id of the web container)

CONTAINER ID        IMAGE                    COMMAND                  CREATED             STATUS              PORTS                    NAMES
65f0b2c36363        paapi_web                 "./docker-entrypoint…"   23 minutes ago      Up 41 seconds       0.0.0.0:3000->3000/tcp   paapi_web_1
bc38cc223991        postgres/postgres:latest   "docker-entrypoint.s…"   27 minutes ago      Up 5 minutes        5432/tcp                 paapi_postgres_1
  1. With container id in hand, you can attach the terminal to the docker instance to get your pry on the attached terminal:
$ docker attach 65f0b2c36363

Resetting everything

Destroy all containers:

$ docker-compose down

Destroy all containers and volumes: (:warning: This will delete your local databases):

$ docker-compose down -v

Locally

Install the project's dependencies using bundler:

$ bundle install

Create the databases

$ bundle exec rails db:setup

Importing PlanningApplications

We can import historical planning applications from a CSV, which should be on S3.

  • Use AWS SSO to get credentials

    1. Copy option 1: Set AWS environment variables (Option 2 probably works as well) export AWS_ACCESS_KEY_ID="123456" export AWS_SECRET_ACCESS_KEY="abcde" export AWS_SESSION_TOKEN="SECRET"
    2. Paste environment into terminal
    3. Verify the environment has been updated
    • $ env

  • Run Import task

$ rake import:planning_applications LOCAL_AUTHORITY=buckinghamshire

Documentation

An API website is available at docs.paapi.services and can be served locally using:

npm run serve:pages

Tests

You can run the full test suite using following command:

$ bundle exec rspec

Debugging using binding.pry

  1. Initially we have installed pry-byebug to development and test group on our Gemfile
group :development, :test do
  # ..
  gem 'pry-byebug'
  # ..
end
  1. Add binding.pry to the desired place you want to have a look on your rails code:
def index
  binding.pry
end

Start the server:

$ rails server

Start a rails console:

$ rails console

Building production docker

Create production docker

docker build -t paapi -f Dockerfile.production .

Run production docker

docker run --rm -it -p 3000:3000 -e DATABASE_URL=postgres://postgres@host.docker.internal:5432/paapi_development -e RAILS_SERVE_STATIC_FILES=true -e RAILS_ENV=production -e RAILS_LOG_TO_STDOUT=true paapi:latest bundle exec rails s

Run production docker bash

docker run --rm -it -e DATABASE_URL=postgres://postgres@host.docker.internal:5432/paapi_development -e RAILS_SERVE_STATIC_FILES=true -e RAILS_ENV=production -e RAILS_LOG_TO_STDOUT=true paapi:latest /bin/bash

Working with api documentation: aggregate swagger files

We need a single openapi file to exist, but to keep the code easier to maintain we have multiple files that are then compiled into this single file:

public/api-docs/v1/_build/swagger_doc.yaml

So to create a new api endpoint, create your yaml doc inside public/api-docs/v1 and reference it in

public/api-docs/v1/swagger_doc.yaml

like so:

  $ref: "./your_new_file_name.yaml"

Make changes to your new file, and when you're happy aggregate them into our single file by installing this package in your machine:

npm install -g swagger-cli

and running:

swagger-cli bundle public/api-docs/v1/swagger_doc.yaml --outfile public/api-docs/v1/_build/swagger_doc.yaml --type yaml

Github Actions

We use Github Actions as part of our continuous integration process to build, run and test the application.