Open Source GeoSocial Intelligence Framework
DOI for current stable release v2.0.0:
Cognicity-rem-server is the NodeJS server module for the CogniCity framework REM interface, responsible for serving data and web content. For detailed framework documentation see http://cognicity.info
- NodeJS version 4.2.1 or later
- PostgreSQL version 9.2 or later, with PostGIS version 2.0 or later
Please refer to package.json for details of dependencies.
Please refer to package.json for details of dependencies.
Download the source code for cognicity-rem-server from github: https://github.com/smart-facility/cognicity-rem-server or view the CogniCity installation documentation at http://cognicity.info.
To check it out using git, run git clone --recursive [email protected]:smart-facility/cognicity-rem-server
, which will also check out the default web site submodule https://github.com/smart-facility/https://github.com/smart-facility/cognicity-rem-web, which if you fork you can change to your own set of pages (refer to config.public_dir and config.url_prefix in the config.js file). If you have already cloned the repository, and want to check out the submodule, then run
git submodule init
git submodule update
To update the submodule, first cd cognicity-rem-web
then git pull origin master
, then cd ..
to move back to the main cognicity-rem-server directory and then git commit
and git push
along with any other changes.
To build on OS X we recommend using homebrew to install node, npm, and required node modules as follows:
brew install node
npm install
To build on Windows we recommend installing all dependencies (making sure to use all 32 bit or all 64 bit, depending on your architecture) plus following the instructions (for Windows 7 follow the Windows 7/8 instructions) for node-gyp and then:
- You need to add C:\Program Files\PostgreSQL\9.3\bin (modifying that location if necessary to point to the installed version of PostgreSQL) to path so the build script finds
pg_config
, and - You need to create the %APPDATA%\npm folder and run cmd (and hence npm) as administrator. %APPDATA% is usually under C:\Users\your_username\AppData\Remote.
- You may need to specify the version of the build tools installed by adding the argument
--msvs_version=2013
to thenpm
command (substituting the appropriate version) Then you can runnpm install
.
For the cognicity-rem-web submodule, install the node dependencies in package.json using NPM as follows:
cd cognicity-rem-web
npm install
You can then run grunt
if you need to rebuild the build products following changes to its source.
Server configuration parameters are stored in a configuration file which is parsed by server.js. See config.js for an example configuration. It is possible to run multiple server instances using different configuration files so long as a unique port is assigned to each instance. Some that you probably want to change:
- config.pg.conString - the database connection string that can include username and password as well as the hostname and database name. If you're deploying to AWS Elastic Beanstalk you will need to configure a property with name DB_NAME and value set to the database name, under Configuration -> Software configuration.
- config.compression - If true, enable Express compression middleware to gzip responses. If deploying standalone then you probably want to set this to true. If deploying behind a reverse proxy+cache like nginx then you will want to leave this config option set to false and enable compressing using the caching server. For Elastic Beanstalk using nginx this is configured automatically using the Elastic Beanstalk config file (note if deploying standalone then this file actually contains only a fragment of an nginx config plus the Elastic Beanstalk headers).
- config.logger.logDirectory - the location of the log file for the server. The default is the current working directory, and the default location + name are set up in the cloud-log-init.config file for easy export of the log file in Elastic Beanstalk.
- aggregates.archive.level - The key of the aggregate level ('config.pg.aggregate_levels') to use for archive aggregate response data
- conString - PostgreSQL connection string see node-postgres module documenation
- reconnectionDelay - Delay between reconnection attempts if postgres connection lost
- reconnectionAttempts - Number of times to attempt to reconnect before dying
- aggregate_levels - Database tables, keys are the label and values are the table name
- infrastructure_tbls - Database tables, keys are the label and values are the table name
Cognicity-rem-server requires a database that conforms to the Cognicity framework schema.
You need to setup the session storage schema - run a command like
psql mydatabase < node_modules/connect-pg-simple/table.sql
See https://github.com/voxpelli/node-connect-pg-simple for more details.
You will also need to import the SQL files from the schema directory.
Configure the 'auth.sessionSecret' value - setting this from the environment is a good approach.
Some users are created by default by the 'create-users.sql' script, or you can create more users manually by inserting them into the database (see how to create passwords).
- The
config.public_dir
parameter is the location of public HTML, CSS, JS web pages to serve. - By default pages are served at [http://localhost:8081/project-name/], the optional prefix URL can be changed using the
config.url_prefix
configuration parameter. - The
config.root_redirect
parameter defines where a client is redirected to if they request the root path of the server
The following routes exist:
/data/api/v2/aggregates/live
- Live aggregates/data/api/v2/rem/flooded
- Flooded states/data/api/v2/rem/dims
- DIMS states
A URL parameter of format=topojson
can be appended to any route to receive the response data in topojson format.
Requests are cached either temporarily (with a timeout set by the config.cache_timeout
parameter) or permanently depending on the route.
The server is launched by node.js directly. Note that you must set the SESSION_SECRET environment variable. In production, software on the server should manage launching, health checking and restarting of the process.
$ cd cognicity-rem-server/
$ SESSION_SECRET=my_secret node server.js config.js
Winston logger writes to [config.instance].log
. The log directory is configurable.
- level - info or debug are most useful here, debug will give you more verbose logging output
- maxFileSize - max size (in bytes) of each log file before a new one is created
- maxFiles - number of log files to retain
- logDirectory - Specify a full path to the log directory. If not specified, the application directory will be used.
There is a git pre-commit hook which will run the 'npm test' command before your commit and will fail the commit if testing fails.
To use this hook, copy the file from 'git-hooks/pre-commit' to '.git/hooks/pre-commit' in your project folder.
cp git-hooks/pre-commit .git/hooks/
To build the JSDoc documentation run the following npm script:
npm run-script build-docs
This will build the HTML API documentation in the folder docs
where you can open it with a web browser.
To build test code coverage documentation, run the following npm script:
npm run-script coverage
This will run istanbul code coverage over the full mocha test harness and produce HTML documentation in the directory coverage
where you can open it with a web browser.
To test make sure nothing is running on tcp port 8082. Note this is different to the default port of 8081, to avoid a conflict while testing on the same system the server is running on. Then run:
npm test
The release procedure is as follows:
- Update the CHANGELOG.md file with the newly released version, date, and a high-level overview of changes. Commit the change.
- Update JSDoc documentation if required (see above).
- Create a tag in git from the current head of master. The tag version should be the same as the version specified in the package.json file - this is the release version.
- Update the version in the package.json file and commit the change.
- Further development is now on the updated version number until the release process begins again.
- The deployed version is always in origin/master.
This software is released under the GPLv3 License. See License.txt for details.