Service directories done right

Example screens from the app

Outpost is a standards-driven service management application, API and comprehensive set of admin tools for managing records about local community services, groups and activities. It is part of the Outpost Platform.

Outpost works alongside a seperate API component and Scout a directory application.

It can also act as an OAuth provider via Doorkeeper.

• Ruby on rails
• PostgreSQL database
• MongoDB database for use with Outpost API (optional)

For more information see getting started

Outpost is 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.

🚨 When deploying Outpost you will need to schedule specific tasks, see configuration for more information.

Since Outpost is designed to be simple to setup we recommend using 12-factor app hosting such as Heroku. However we do provide a docker image to host your own instance.

Please not that heroku will automatically setup SECRET_KEY_BASE for you but in docker you will need to do this manually.

You can see examples of how to set up the environment in the makefile. The production image defines an entrypoint and a cmd, the default entrypoint is /start and the default cmd is web. We're using herokuish to replicate a similar deployment environment to heroku so this replicates the setup.

By default when running the container it will just run the rails application, you can then update the cmd to one in the procfile or you can define your own entrypoint file

#!/bin/sh
# https://stackoverflow.com/a/38732187/1935918
set -e

if [ -f tmp/pids/server.pid ]; then
  rm tmp/pids/server.pid
fi

bin/herokuish procfile exec rake db:migrate

bin/herokuish procfile exec "$@"

For more information see getting started

For now we recommend using docker to run the application locally as this ensures that the versions are as close to the production environment as possible.

cp -rp sample.env .env
docker compose up -d

# setup dummy data and example user login
docker compose exec outpost bin/rails SEED_ADMIN_USER=true SEED_DUMMY_DATA=true SEED_DEFAULT_DATA=true db:seed

This will setup outpost, mongo, postgres and the outpost-api-service on your machine.

• Outpost: http://localhost:3000
• Outpost API service: http://localhost:3001
• You can connect to the the postgres database locally using localhost:5433
• You can connect to the mongo database locally using localhost:27018

You can log in with [email protected] and the initial password you set in the configuration

See configuration for setting up environmental variables.

Populate with dummy data

# create a default admin user
docker compose exec outpost bin/rails SEED_ADMIN_USER=true db:seed

# create dummy data
docker compose exec outpost bin/rails SEED_DUMMY_DATA=true db:seed

# default accessibilities, send_needs and suitabilities only
docker compose exec outpost bin/rails SEED_DEFAULT_DATA=true db:seed

# all of the above
docker compose exec outpost bin/rails SEED_ADMIN_USER=true SEED_DUMMY_DATA=true SEED_DEFAULT_DATA=true db:seed

The application will be running on localhost:3000.

Populate mongo database

docker compose exec outpost bin/rake build_public_index

Run the rails console

docker compose exec outpost bin/rails c

Run tests

docker compose exec outpost bundle exec rspec

Run end to end tests

docker compose exec outpost rake

Outpost dev-base

If you need to you can build the outpost-dev-base image locally, you will need to update the Dockerfile FROM to use your local version as well.

docker build --progress=plain -f .docker/images/dev-base/Dockerfile -t outpost-dev-base .

For more documentation on how to use Outpost see the documentation

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

The following environmental variables are required for minimal setup of Outpost.

Environment specific

Databases

Emails

Google Maps

Initialisation and setup

You can make use of the INITIAL_ADMIN_PASSWORD environmental variable when initialising your application.

Deprecated

The following ENV variables are or will soon be deprecated.

Outpost depends on on several important rake tasks. To run these tasks use bin/rake task:name.

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

There is a settings page located at /admin/settings/edit where you can configure certain aspects of the Outpost interface.

A user will need to have the superadmin permission in order to access this page. This permission can currently only be set through the command line.

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

You can run bin/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.

See documentation on data import.

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.

Currently these are only used in the settings page to replace the site logo so these details are not required.

Outpost can integrate with the Ofsted API to bring in a list of records and create service entries from them.

The following ENV vars are used to enable this functionality

NB this feature is subject to change at any time

There is a feature called directories in Outpost which lets you configure named directories or teams, this changes the interface so that services can be viewed all together or per directory, for example Family information services and Adult Social Care.

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.

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

bundle exec rspec

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.

Its also a good idea to check that assets are able to be precompiled before deploying

bundle exec rails assets:precompile