Outpost image


service directories platform

From GitHub

Local government service directories done right, in an API-standards driven way.


Readme from GitHub

Service directories done right

Example screens from the app

Run tests

Staging site here

A standards-driven API and comprehensive set of admin tools for managing records about local community services, groups and activities.

Outpost works alongside a seperate API component.

We're also building an example front-end for Outpost.

๐Ÿงฑ How it's built

It's a Rails app backed by a PostgreSQL database.

It can also act as an OAuth provider via Doorkeeper.

It uses Google APIs for geocoding and map features, and Sendgrid to send emails.

๐Ÿ’ป Running it locally

For more information see getting started

You need ruby and node.js installed, plus a PostgreSQL server running.

If you want to build a public index for the API, you'll also need a local MongoDB server.

First, clone the repo. Then:

bundle install
rails db:setup
rails s

# run end-to-end and unit tests

The database will be seeded with realistic fake data.

It will be on localhost:3000. You can log in with [email protected] and the initial password you set [in the configuration](#-configuration).

With multiple directories

To see multiple directories in Outpost, run the app with:

INSTANCE=buckinghamshire rails s

This will start the app with the directories listed in config/app_config.yaml.

To add more directories, or set up another instance with separate directories,
edit config/app_config.yaml.

With Docker

With docker-compose and docker, after cloning the project:

  • Bring up the databases with docker-compose up
  • Populate your environment variables
  • Run the application with rails s

Building a public index

Outpost's API component relies on a public index stored on MongoDB.

You can run rails build_public_index to build the public index for the first time. Active record callbacks keep it up to date as services are changed.

๐ŸŒŽ Running it on the web


It's suitable for 12-factor app hosting like Heroku.

It has a Procfile that will automatically run pending rails migrations on every deploy, to reduce downtime.

๐Ÿ—“ Administrative tasks

Outpost depends on on several important rake tasks.

Some of these can be run manually, and some are best scheduled using Heroku Scheduler or similar.

Task Description Suggested schedule
open_objects:import Run the bespoke import job from Open Objects. For this to succeed, you need several source CSV data files in the /lib/seeds folder. Will take a long time. One-off
build_public_index Build the initial public index for the API service to use. One-off
process_permanent_deletions Permanently delete any services and users that have been "discarded" for more than 30 days. Weekly
ofsted:create_initial_items Build the initial Ofsted items table One-off
ofsted:update_items Check for any changes to Ofsted items against the Ofsted API Daily, overnight
update_counters:all Update the counter caches to keep them in sync Daily, overnight

๐Ÿงฌ Configuration

You can provide config with a .env file. Run cp .env.example .env to create a fresh one.

It needs the following extra environment variables to be set:

Variable Description Example Required?
GOOGLE_API_KEY with the geocoding API enabled, to geocode postcodes Yes, for geocoding features
GOOGLE_CLIENT_KEY with the javascript and static maps APIs enabled, to add map views to admin screens Yes, for map features
OFSTED_API_KEY and OFSTED_FEED_API_ENDPOINT to access the feed of Ofsted items Only if running Ofsted rake tasks
NOTIFY_API_KEY to send emails with Notify In production only
NOTIFY_TEMPLATE_ID ID of a notify template, as described here In production only
MAILER_HOST where the app lives on the web, to correctly form urls in emails https://example.com In production only
FEEDBACK_FORM_URL a form where users can submit feedback about the website https://example.com In production only
DATABASE_URL the main PostgreSQL database postgres://user:password
Yes, if different from default, and in production
DB_URI the MongoDB database for the public index mongodb://user:password
Yes, if using the API service
INITIAL_ADMIN_PASSWORD an initial admin password to log in with for local development Locally only
SHOW_ENV_BANNER show a bright warning banner on non-production environments staging Only to warn about non-production environments
GCP_PROJECT Name of the google cloud project * No
GCP_BUCKET Name of the google cloud bucket * No
GCP_PROJECT_ID Name of the google cloud project id * No
GCP_PRIVATE_KEY_ID Google cloud private key id * No
GCP_PRIVATE_KEY Google cloud private key * No
GCP_CLIENT_EMAIL Google cloud client email * No
GCP_CLIENT_ID Google cloud client id * No
GCP_CLIENT_X509_CERT_URL Google cloud x509 certificate * No

๐Ÿ’ฟ Data import

See documentation on [data import](lib/tasks/data_import/README.md).

๐Ÿ” OAuth provider

Outpost can work as an identity provider for other apps. Users with the highest permissions can access the /oauth/applications route to create credentials.

Once authenticated, consumer apps can fetch information about the currently logged in user with the /api/v1/me endpoint.

๐Ÿงช Tests

It has some rspec tests on key functionality. Run them with:

bundle exec rspec

Code coverage

SimpleCov and Codecov are set up to track code coverage. To see the code
coverage on a local branch, run the test suite and open coverage/index.html:

open coverage/index.html

The coverage report is sent to Codecov after the tests run in CI. Once you open
a PR, Codecov will post a comment with a handy coverage delta and a link to view
line-by-line coverage for the PR.