Service directories done right

---

Example screens from the app

---

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
yarn
rails db:setup
rails s

# run end-to-end and unit tests
rake

The database will be seeded with realistic fake data.

It will be on localhost:3000. You can log in with example@example.com and the initial password you set in the 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 @example.com:5432/database	Yes, if different from default, and in production
DB_URI	the MongoDB database for the public index	mongodb://user:password @example.com/database	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.

🔐 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:

rake
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.