README.md in peoplefinder-0.0.2 vs README.md in peoplefinder-0.1.0

- old
+ new

@@ -2,32 +2,46 @@ This is a rails engine that can be mounted inside a rails 4 application. A working example can be seen at https://github.com/alphagov/gds-peoplefinder -## Preparing the Gemfile +## Creating your own wrapper application -In Gemfile: +If you want to deploy peoplefinder yourself, you can create your own wrapper +application quite easiliy. -`gem 'peoplefinder'` +Start by creating a bare rails application: -The peoplefinder engine requires some forked / tagged versions gems -so these need to be included also: +``` +$ rails application new my_peoplfinder +``` -`gem 'carrierwave', - git: 'https://github.com/carrierwaveuploader/carrierwave.git', - tag: 'cc39842e44edcb6187b2d379a606ec48a6b5e4a8'` +Then you need to modify the `Gemfile` to include the peoplefinder engine gem: -`gem 'omniauth-gplus', - git: 'https://github.com/ministryofjustice/omniauth-gplus.git'` +``` +gem 'peoplefinder' +``` +The peoplefinder engine requires some forked / tagged versions gems. It's not +possible to specify these forked requirements in the `peoplefinder` gemspec, +so you need to specify them in the `Gemfile` of the wrapper application: -Install the gems with bundler: +``` +gem 'carrierwave', + git: 'https://github.com/carrierwaveuploader/carrierwave.git', + tag: 'cc39842e44edcb6187b2d379a606ec48a6b5e4a8' -`bundle install` +gem 'omniauth-gplus', + git: 'https://github.com/ministryofjustice/omniauth-gplus.git' +``` +Install the gems with bundler: +``` +bundle install +``` + ## Mounting the engine In config/routes.rb: `mount Peoplefinder::Engine, at: "/"` @@ -47,29 +61,33 @@ ` $ bundle exec rake db:migrate` And commit the `schema.rb` -##Configurable elements +## Configuration These should be defined in the config/application.rb or in the enviroments/__environment__.rb files if the settings need to be defined on a per environment basis. `config.app_title` e.g. 'My New People Finder' `config.default_url_options` e.g. { host: mail.peoplefinder.example.com } +`config.disable_profile_tags` Hide the tagging (Skills and expertise) functionality from the edit profile page + +`config.disable_token_auth` Disable the 'token-based authentication' feature + +`config.disable_communities` Disable the 'communities' feature + `config.elastic_search_url` Required for production (see Search section below) `config.ga_tracking_id` Google Analytics tracking id [optional]. e.g. 'XXXX-XXX' `config.support_email` e.g. 'peoplefinder-support@example.com' -`config.valid_login_domains` Restrict login to email addresses from the list of valid domains. e.g. %w[ peoplefinder.example.com ] +`config.valid_login_domains` Restrict login to email addresses from domains that match the string or regular expresson. e.g. `[/(.*)\.gov\.uk\Z/, 'example.com']` - - ## Authentication Authentication requires two environment variables. You can obtain these by visiting the [Google Developers Console](https://console.developers.google.com/) and selecting **APIs & auth** from the sidebar, followed by **Credentials**, @@ -83,10 +101,21 @@ For local development, you can use a `.env` file; see `.env.sample` for an example. The permitted domains are configured in `config/application.rb`. +## Token-based authentication + +An alternative 'token-based' authentication method is also supported. The +token authentication method relies upon the users access to their email +account to authenticate them. + +Each time the user wishes to start a session, they need to generate an +authentication token. This can be done by entering their email address on the +login screen. They will be sent an email message containing a link with a +unique random token. Clicking on the link will allow them to login. + ## Search To run the engine in production mode, `config.elastic_search_url` must be set in, for example, config/application.rb. See 'Configurable elements' above. @@ -100,20 +129,27 @@ Elasticsearch requires [jdk version 7 or greater](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html). If you get an IndexMissingException, you will need to index the Person model: -`bundle exec rake environment elasticsearch:import:model CLASS='Person' FORCE=y` +``` +bundle exec rake environment elasticsearch:import:model CLASS='Peoplefinder::Person' FORCE=y +``` -Or you can build the index from the console: +Or you can create the index from the console: -`Person.__elasticsearch__.create_index! index: Person.index_name, force: true` -`Person.import` +``` +Peoplefinder::Person.__elasticsearch__.create_index! index: Peoplefinder::Person.index_name, force: true` +``` +And populate it: + +`Peoplefinder::Person.import` + You can also delete the index: -`Person.delete_indexes` +`Peoplefinder::Person.delete_indexes` To run specs without Elasticsearch: `bundle exec rspec . --tag ~elastic` @@ -133,100 +169,56 @@ Also, if you'd like test coverage for Javascript you'll need to have Node and Istanbul installed. The easiest way to do this is installing Node via nvm and then use npm to install Istanbul like so: `npm install -g istanbul` -## Utilities +## View templates -CI by [Travis](https://travis-ci.org/ministryofjustice/peoplefinder). +The application layout is set by the [moj_internal_template](https://github.com/ministryofjustice/moj_internal_template) that is installed as part of this engine. -Software metrics by [Code Climate](https://codeclimate.com/github/ministryofjustice/peoplefinder) +You can override this layout in wrapper application, create your own file: -## Releases +`app/views/layouts/peoplefinder/peoplefinder.html.haml` -Within the bin directory there is a file called release.sh. The purpose of this script is for management of releases i.e tagged versions compatible with Githubs release conventions. -To create a new release: +## Angular.js notes -`bin/release.sh create` +The organisational browser uses angular.js. When heroku compiles the assets, the minified js is mangled and does not work. -Listing all releases: +Asset mangling is prevented in the engine with help of the uglifier gem. -`bin/release.sh list` +Make sure that this is not overwritten in the wraper by commenting out the js_compressor in config/environments/production.rb: -Deleting a particular release: +`# config.assets.js_compressor = :uglifier` -`bin/release.sh remove RELEASE_VERSION` -Perform a git show of a release: +## Translation file -`bin/release.sh show RELEASE_VERSION` +A lot of the text in the views is configurable in the translations file. -List all releases with verbose output: +You can override these in wrapper application by creating your own file: -`bin/release.sh ll` +`config/locales/en.yml` -Last release: +## Utilities -`bin/release.sh last` +CI by [Travis](https://travis-ci.org/ministryofjustice/peoplefinder). -##Deployment +Software metrics by [Code Climate](https://codeclimate.com/github/ministryofjustice/peoplefinder) -For this example we're making the following assumptions: +## Reminders -- You're using Heroku -- You've setup staging and production environments as git remotes that we'll henceforth refer to as staging and production - -First if you don't already have a release, create a new one from the current branch: - -`bin/release.sh create` - -The name of the tagged released should be echoed back to the console. And will read back like release/ISO_DATE_TIME. -Copy and past it as an argument together with '^{}:master' appended to the configured git remote of your choosing. For this example we'll use staging. - -`git push -f staging release/2014-08-08T08.59.09Z^{}:master` - -You should then see the standard git based deployment process for Heroku kick into action. - -It should be noted that depending on your circumstances e.g running migrations etc. You may want to run the following sequence of commands: - -`heroku maintenance:on` maintenance mode on - -`heroku ps:scale worker=0` scale down any background workers - -`git push -f staging release/2014-08-08T08.59.09Z^{}:master` push the code to heroku - -`heroku run rake db:migrate` run your migrations - -`heroku ps:scale worker=1` turn your workers back on - -`heroku maintenance:on` unleash the app to the world - - -##SSL - -If you look in the .env.example you'll see a setting called SSL_ON which defaults to false. However the application is fully able to take advantage of -SSL and by setting SSL_ON to true it will force the application to use SSL only which you'll definitely want for production. - -To do this on Heroku run: - -`heroku config:set SSL_ON=true` - - -##Reminders - If the Peoplefinder is to be successful, profiles need to be populated and maintained. -###Inadequate profiles +### Inadequate profiles To view a list of people whose profiles are deemed to be 'inadequate' (not having a phone number, location and photo): `rake peoplefinder:inadequate_profiles` To send emails prompting people to complete their profiles: `rake peoplefinder:inadequate_profile_reminders` - ##Environment Variables ###Support