| | | | | | --- | --- | --- | --- |

Reformed Churches Locator

Want to find a reformed church in Timbuktu? Reformed Churches Locator is a web application that will provide a searchable, user-editable map and directory of all Reformed churches in the world. It will aggregate congregations' contact info via data feeds from various sources, and provide a JavaScript widget containing a map & directory that can be embedded into your website using a simple code snippet (like embedding a YouTube video). It will federate filtered sets of congregation data to other Reformed Churches Locator nodes via CouchDB's filtered replications. The intended result is that Reformed Churches Locator will become the source of the most up-to-date contact info for Reformed churches, and will simplify the job of creating a denominational church directory.

Reformed Churches Locator will recreate the map & congregations components of PresbyterySite (http://sourceforge.net/projects/presbyterysite), but host & serve the congregation data in a federated or peer-to-peer fashion in order to manage data from all Reformed churches rather than from only one presbytery.

Application Architecture

Please note that older Reformed Churches Locator issues which describe the overall application architecture are hosted at https://blueprints.launchpad.net/reformedchurcheslocator.

Reformed Churches Locator is an "Offline first" application, meaning it will run well offline, then sync its data to the server when it has an internet connection. It uses Hoodie to store the app's data locally using PouchDB, and syncs to CouchDB on the server through Hoodie's server-side API.

Installation

The following instructions are specific to installing this application on Ubuntu Linux. Installation on other operating systems is not documented.

Install system-level dependencies

Install Node.js, CouchDB, & Git

$ sudo apt-get install couchdb nodejs git

Verify you're running Node 0.12.x or above:

$ node --version

The version should be at or above 0.12.x.

If you don't have Node.js installed, or you have a lower version, go to nodejs.org and click on the big green Install button.

Install user- and app-level dependencies

$ npm install -g gulp bower && npm install && bower install

Set Hoodie's admin password

$ hoodie start -n

Enter an admin password here. If you don't, you'll need to remove the data directory with this command:

$ # rm -rf data

then run hoodie start again to enter the password.

After you set the password, type CTRL-C in the terminal to kill the Hoodie process.

Run Reformed Churches Locator

Then run Reformed Churches Locator by running the following commands in your terminal:

$ git clone https://github.com/timblack1/rcl.git
$ npm start

This should open up a copy of the application in your web browser.

Development workflow

Serve / watch

$ npm start

This outputs an IP address you can use to locally test and another that can be used on devices connected to your network.

Run tests

$ npm test

This runs the unit tests defined in the app/test directory through web-component-tester.

To run tests Java 7 or higher is required. To update Java go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and download JDK and install it.

Deployment

Because the application is still in development, we have not yet documented how to deploy it to a server.

Frequently Asked Questions

Something has failed during installation. How do I fix this?

Our most commonly reported issue is around system permissions for installing Node.js dependencies. We recommend following the fixing npm permissions guide to address any messages around administrator permissions being required. If you use sudo to work around these issues, this guide may also be useful for avoiding that.

If you run into an exception that mentions five optional dependencies failing (or an EEXIST error), you may have run into an npm bug. We recommend updating to npm 2.11.0+ to work around this. You can do this by opening a Command Prompt/terminal and running npm install [email protected] -g. If you are on Windows, Node.js (and npm) may have been installed into C:\Program Files\. Updating npm by running npm install [email protected] -g will install npm into %AppData%\npm, but your system will still use the npm version. You can avoid this by deleting your older npm from C:\Program Files\nodejs as described here.

If the issue is to do with a failure somewhere else, you might find that due to a network issue a dependency failed to correctly install. We recommend running npm cache clean and deleting the node_modules directory followed by npm install to see if this corrects the problem. If not, please check the issue tracker in case there is a workaround or fix already posted.

Recipes for further development of this app

• Add ES2015 (formally ES6) support using Babel
• Polymer Performance Recipe
• Deploy to Github Pages
• Deploy to Firebase using Pretty URLs
• Use PSK for Mobile Chrome Apps