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
Variable | Description | Example | Required? |
---|---|---|---|
SHOW_ENV_BANNER |
show a bright warning banner on non-production environments | staging | Only to warn about non-production environments |
RAILS_ENV |
Rails environment | production | No, defaults to production |
NODE_ENV |
Node environment | production | No, defaults to production |
PROJECT_NAME |
Determines the name of the group in docker | outpost_development | No |
LANG |
Determines the default language | en_US.UTF-8 | No |
RAILS_SERVE_STATIC_FILES |
Tells rails to serve static assets | true | Yes in production when using docker |
SECRET_KEY_BASE |
In docker environment required to compile assets successfully run: RAILS_ENV=production rake secret to generate |
randomlettersandcharacters | Yes in production when using docker |
Databases
Variable | Description | Example | Required? |
---|---|---|---|
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 |
Emails
Variable | Description | Example | Required? |
---|---|---|---|
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_FROM |
Who are the emails sent from Outpost from | [email protected] | In production only |
MAILER_HOST |
where the app lives on the web, to correctly form urls in emails | https://example.com | In production only |
Google Maps
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 |
Initialisation and setup
You can make use of the INITIAL_ADMIN_PASSWORD
environmental variable when initialising your application.
Variable | Description | Example | Required? |
---|---|---|---|
INITIAL_ADMIN_PASSWORD |
an initial admin password to log in with for local development | Locally only | |
MONGO_INITDB_DATABASE |
Name of database to create and initialise in docker container | outpost_production | No |
POSTGRES_USER |
User to create and initialise in docker container | outpost_production | No |
POSTGRES_PASSWORD |
Database password to create and initialise in docker container | outpost_production | No |
POSTGRES_DB |
Name of database to create and initialise in docker container | outpost_production | No |
Deprecated
The following ENV variables are or will soon be deprecated.
Variable | Description | Example | Required? |
---|---|---|---|
INSTANCE |
Instance name, used with the directories feature and to customise some parts of the interface | buckinghamshire | No |
FEEDBACK_FORM_URL |
a form where users can submit feedback about the website | https://example.com | In production only |
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.
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 |
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.
Variable | Description | Example | Required? |
---|---|---|---|
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 |
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
Variable | Description | Example | Required? |
---|---|---|---|
OFSTED_API_KEY |
to access the feed of Ofsted items | Only if running Ofsted rake tasks | |
OFSTED_FEED_API_ENDPOINT |
to access the feed of Ofsted items | Only if running Ofsted rake tasks |
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