Installation For Development/Contributing

1. Install the MEAN-stack components nodejs/npm and mongodb

   nodejs
   Install MongoDB Community Edition

   Installation may require root access. If the ScriptRemote server will use an existing, shared MongoDB service then you will need to set the MONGO_URL or MONGO_HOST_PORT environment variable (see config/env/development.js) and you may need to add MongoDB credentials to the .env file in Step 3.

   Also if not already present install:

   • git
   • grunt (install globally)

   For bash testing install:

   • curl
   • openssl

   For python2.7 testing install:

   • pip
   • passlib
   • pycrypto


2. Clone ScriptRemote

   If you plan to contribute to the project then the clone would be from your forked repo instead of scriptremote.

   >$ cd ~ (or your preferred install location)
   >$ git clone https://github.com/jimb245/scriptremote | 
   >$ cd scriptremote
   ~$ cp npm-shrinkwrap-dev.json npm-shrinkwrap.json
   >$ npm install
   >$ cd public/lib/forge-bower
   >$ npm install
   >$ npm run minify
   



3. Set up credentials/secrets

   First set up an email forwarding account. This will be used to send various security-related messages and user notifications. Copy the sample credentials file and substitue your values for the MAILER dummy values:

   >$ cd ~/scriptremote
   >$ cp credentials.env .env
   >$ chmod 600 .env
   >$ vim .env
   

   Some services are stricter than others about relaying mail. To help ensure that mail can be sent choose the same provider as expected for registered user emails, and set MAILER_FROM to the same address as MAILER_EMAIL_ID. Any mailing errors will be logged to the console. If there is a problem it will probably first show up when registering the admin user below.

   Second, generate a random string for the session middleware. For example:

   >$ openssl rand -base64 32
   

   Substitute the result for the SESSION_SECRET value in .env


4. Test the server

   >$ grunt development
   

   This should start the server listening on localhost:3000. Check that you can access the site with a browser.

Code Organization

Code organization is roughly similar to meanjs.org v0.3.

Server code is in directory app. Registration, login, and password reset pages are handled by the server directly rather than by the Angular framework. The login page is compatible with password managers. The server template manager is handlebars and the template layouts are in app/views/layouts, one for the server-managed pages and one for Angular.

Public files are in directory public. The Angular-based code is in public/modules. The bash and python script utilities and their tests are in public/scripts. Doc files other than README.md are in doc.

Config files are located in config/env. The server configuration is determined by the NODE_ENV environment variable. The defined configuration values are:

• development
• test
• production (http server)
• secure (https server)
• cloudfoundry (upload to platform)

The displayed release version is set in config/env/all.js.

The server startup files are server.js, and server_mod.js which returns a promise that is useful in test initialization.

Grunt Tasks

• Development server

   >$ grunt 

  Starts a server using the development configuration, on localhost:3000, mongo database scriptremote-dev, plus concurrent watch tasks.

   >$ grunt development

  Starts a server using the development configuration, on localhost:3000, mongo database scriptremote-dev, no concurrent tasks.

• Lint

   >$ grunt lint

  Runs jshint, csslint

• Test

   >$ grunt testserver

  Starts a server using the test configuration, on localhost:3000, mongo database scriptremote-test, no concurrent tasks.

   >$ grunt test

  Runs all tests on localhost:3000, mongo database scriptremote-test Requires pre-registration of admin user in the test database and setting environment variables SRADMINEMAIL, SRADMINPASSWORD.

  There are ~400 unit tests, of four types:

  • Bash utility script tests based on bats
  • Python utility script tests based on nose
  • Angular client unit tests based on karma, jasmine, phantomjs
  • Server unit tests based on mocha, should, supertest

  If the HTTP 429 error occurs during a test run it is probably because the brute force login protection data has become stale. To clear it use the mongo commandline utility to connect to the scriptremote-test database and delete the bruteforce collection.

  There are no automated end-to-end tests yet.

• Build for release configurations (production, secure, cloudfoundry)

   >$ grunt build

  Does compression, cache busting, string substitution, document generation, shrinkwrapping. Runs in the development configuration. The generated outputs are in directories:

  • public/dist
  • public/doc
  • app/routes/api/api.server.routes.js
  • npm-shrinkwrap.json
  • npm-shrinkwrap-dev.json

  public/dist includes the minified front-end code and libraries and is under version control. The non-release configurations (developement, test) instead load individual libraries from public/lib and code from public/modules.

  The task substitutes the version string into package.json and into copies of the script utility files in public/dist. For cache busting it includes the version or a hash string in the names of libraries in public/dist.

Additional References:

MEAN.JS
MEAN.IO
An Introduction To The MEAN Stack