Permalink
Browse files

Updated docs and DB connection callbacks

  • Loading branch information...
samluescher committed Feb 5, 2013
1 parent 6713fe8 commit cbdfaead573339f44afc120edc4b87ca3bf87f7f
Showing with 106 additions and 98 deletions.
  1. +78 −34 README.md
  2. +3 −5 api/import.js
  3. +1 −45 docs/howto.txt
  4. +1 −1 manage.js
  5. +6 −7 server.js
  6. +17 −6 utils.js
View
112 README.md
@@ -1,65 +1,109 @@
-## What's GeoSense?
+## What is GeoSense?
-An open publishing platform for visualization, social sharing, and data analysis of geospatial data.
+GeoSense is an open publishing platform for visualization, social sharing, and analysis of geospatial data. It aims to simplify the process of turning large
+data collections into beautiful, interactive online maps.
-## Building
+## How to install GeoSense on your development machine
-Step 1: Run:
+The project is built on top of [Node.js](http://nodejs.org/) and uses
+[mongoDB](http://www.mongodb.org/) as database. Please install Node.js with
+NPM and mongoDB on your system first. There are installers and packages
+available for many operating systems.
- node r.js -o public/libs/app.build.js
+To get the GeoSense code, you can either download it from
+[GitHub](https://github.com/Safecast/GeoSense) and extract it to a folder on
+your harddrive, or clone the repository using [Git](http://git-scm.com/)
+(recommended so you can easily update to newer versions at a later point):
-from project root.
+ $ git clone git://github.com/Safecast/GeoSense.git
-Step 2: Overwrite public with public-optimized before pushing to Heroku
+Next, change into the GeoSense folder and install the dependencies using NPM:
-## Management commands
+ $ cd GeoSense
+ $ npm install
-### Importing a new file from scratch:
+You should now be ready to run the GeoSense development server.
- node ./manage.js import --url https://api.safecast.org/system/measurements.csv --format csv --converter safecast
-*or*
+## Running the development server
+
+Before you run the development server, make sure to start mongoDB, either in
+its own terminal window:
+
+ $ mongod
+
+or as a background service:
+
+ $ mongod --fork --logpath /var/log/mongodb.log
+
+You can then run the development server using the following command from the
+GeoSense folder:
+
+ $ node server.js NODE_ENV=development node server.js
+
+You should get a success message such as `Web server running at
+http://0.0.0.0:3000/`. You'll now be able to open GeoSense in your web
+browser by typing `http://localhost:3000` in the location field.
+
- node ./manage.js import --path path/to/file.csv --format csv --converter safecast
+## Command-line interface
-### Later, after the initial import, you might want to re-fetch the source file and sync your local data:
+In addition to the Graphical User Interface running in your web browser,
+GeoSense comes with a Command-Line Interface (CLI) that enables you to script
+certain tasks and perform them without user interaction. CLI actions include
+data import and aggregation into map grids.
- node ./manage.js sync <collectionId> [options]
+To run the CLI, run the following command from the GeoSense folder:
-T# his basically runs the import command again, with the same arguments. You can override these by passing options to the command, for instance the following would sync the collection with data from a *different* URL>:
+ $ node manage.js
- node ./manage.js sync <collectionId> --url https://api.safecast.org/api/<incremental-dump>
+This will display a list of available CLI actions, such as `import`. For
+example, to display a list of all existing point collections in the database,
+type:
+ $ node manage.js list-collections
-## Updating and re-crunching a collection
+To receive more information about a specific action, pass `help` followed by
+the action name to the CLI, for instance:
-cd into project root on production server
-node ./manage.js sync Safecast
-mongo penny.mongohq.com:10065/app4772485 -u USER -p PASSWORD ./config.js ./scripts/reduce-points.js
+ $ node manage.js help import
+
+
+### The `import` action
+
+Usage: `node manage.js import [import-params]`
+
+Imports records from a URL or a file into a new point collection.
+
+For example, to import a new data file from scratch, type:
+
+ $ node ./manage.js import --url https://api.safecast.org/system/measurements.csv --format csv --converter safecast
+
+*or*
+ $ node ./manage.js import --path path/to/file.csv --format csv --converter safecast
-## Running Dev server
+Later, after the initial import, you might want to re-fetch the source file and sync your local data:
- NODE_ENV=development nodemon server.js
+ $ node ./manage.js sync <collectionId> [options]
-## Mongo dumping and cloning
+This basically runs the import command again, with the same arguments. You can override these by passing options to the command, for instance the following would sync the collection with data from a *different* URL>:
- mongodump -d geo -o ./dump
- mongorestore -h penny.mongohq.com:10065 -d DATABASE -u USER -p PASSWORD --drop ./dump/geo/
+ $ node ./manage.js sync <collectionId> --url https://api.safecast.org/api/<incremental-dump>
-### For dev server:
-
- mongorestore -d geo --drop ./dump/geo/
-### For prod server:
+### The `mapreduce` action
- mongorestore -h penny.mongohq.com:10065 -d app4772485 -u safecast -p PASSWORD --drop ./dump/geo/
+TODO: document most important CLI actions.
-## Executing reduction script
+## Building the project for deployment
- mongo DATABASE -u USER -p SEKRET config.js scripts/reduce-points.js
+GeoSense utilizes [RequireJS](http://requirejs.org/) to create an optimized
+build for faster page load times. To create a build, run the following command
+from the GeoSense folder:
-### For dev server:
+ $ node r.js -o public/libs/app.build.js
- mongo geo config.js scripts/reduce-points.js
+You now have an optimized copy of the `public/` folder ready for deployment
+under `public-build`.
View
@@ -608,20 +608,18 @@ ImportAPI.prototype.cli = {
'list-collections': function(params, callback, showHelp)
{
if (utils.connectDB()) {
- console.log('Existing collections:');
PointCollection.find({}).run(function(err, docs) {
if (!err) {
+ console.success('Existing collections:', docs.length);
docs.forEach(function(doc) {
- console.log(' *', doc._id, doc.title);
+ var dump = {_id: doc._id, title: doc.title, status: doc.status, "...": "..."};
+ console.log('*', dump);
});
}
callback(err);
});
}
}
-
-
-
}
View
@@ -1,37 +1,3 @@
-Management commands
-===================
-
-Importing a new file from scratch:
-
- node ./manage.js import --url https://api.safecast.org/system/measurements.csv --format csv --converter safecast
-
-*or*
-
- node ./manage.js import --path path/to/file.csv --format csv --converter safecast
-
-Later, after the initial import, you might want to re-fetch the source file and sync your local data:
-
- node ./manage.js sync <collectionId> [options]
-
-This basically runs the import command again, with the same arguments. You can override these by passing options to the command, for instance the following would sync the collection with data from a *different* URL>:
-
- node ./manage.js sync <collectionId> --url https://api.safecast.org/api/<incremental-dump>
-
-
-Updating and re-crunching a collection
-======================================
-
-<cd into project root on production server>
-node ./manage.js sync Safecast
-mongo penny.mongohq.com:10065/app4772485 -u USER -p PASSWORD ./config.js ./scripts/reduce-points.js
-
-
-Running Dev server
-==================
-
- NODE_ENV=development nodemon server.js
-
-
Mongo dumping and cloning
=========================
@@ -42,16 +8,6 @@ For dev server:
mongorestore -d geo --drop ~/tmp/dump/geo/
-For prod server:
+For Safecast production server:
mongorestore -h penny.mongohq.com:10065 -d app4772485 -u safecast -p PASSWORD --drop .~/tmp/dump/geo/
-
-
-Executing reduction script
-==========================
-
- mongo DATABASE -u USER -p SEKRET config.js scripts/reduce-points.js
-
-For dev server:
-
- mongo geo config.js scripts/reduce-points.js
View
@@ -13,7 +13,7 @@ if (!module.parent) {
var args = optimist.argv,
help = 'Usage: node manage.js <command> [options]\n or: node manage.js help <command> to show help for a specific command.';
- console.log('GeoSense command-line utility');
+ console.info('*** GeoSense command-line utility ***');
var runCliCommand = function(args) {
var showHelp = args._[0] == 'help';
View
@@ -6,20 +6,17 @@ var application_root = __dirname,
models = require('./models.js'),
utils = require('./utils.js'),
permissions = require('./permissions.js'),
- ejs = require('ejs');
+ ejs = require('ejs'),
+ console = require('./ext-console');
var templates;
var port = process.env.PORT || 3000;
var app = express();
-console.log('*** connecting to db ***', config.DB_PATH);
-mongoose.connect(config.DB_PATH);
-
-
app.configure(function() {
var staticDir = __dirname
+ (process.env.NODE_ENV == 'production' ? '/public-build' : '/public');
- console.log('Serving static files from '+staticDir);
+ console.info('Serving static files from '+staticDir);
app.use(express.static(staticDir));
app.use(express.logger('dev'));
app.use(express.compress());
@@ -42,6 +39,8 @@ app.configure(function() {
app.set('views', path.join(application_root, "views"));
});
+utils.connectDB();
+
var API = require('./api');
new API(app);
@@ -166,7 +165,7 @@ utils.loadFiles(['public/base.html'], __dirname, function(err, contents) {
} else {
templates = contents;
app.listen(port, "0.0.0.0");
- console.log('Server running at http://0.0.0.0:' + port + "/");
+ console.success('Web server running at http://0.0.0.0:' + port + "/");
}
});
View
@@ -5,6 +5,23 @@ var config = require('./config.js'),
mongoose = require('mongoose'),
console = require('./ext-console');
+exports.connectDB = function(exitProcessOnError)
+{
+ mongoose.connection.on('open', function (ref) {
+ console.success('Connected to mongoDB server.');
+ });
+
+ mongoose.connection.on('error', function (err) {
+ console.error('mongoDB connection error:', err.message);
+ if (exitProcessOnError == undefined || exitProcessOnError) {
+ process.exit(1);
+ }
+ });
+
+ console.info('Connecting to database', config.DB_PATH);
+ return mongoose.connect(config.DB_PATH).connection;
+};
+
/**
* Simple Python-style string formatting.
*
@@ -108,12 +125,6 @@ exports.sendEmail = function(to, subject, bodyTemplate, replacements, callback)
});
}
-exports.connectDB = function(callback) {
- console.info('*** connecting to db ***', config.DB_PATH);
- return mongoose.connect(config.DB_PATH, callback);
-};
-
-
exports.handleDbOp = function(req, res, err, op, name, permissionCallback)
{
if (err) {

0 comments on commit cbdfaea

Please sign in to comment.