MEAN.io

MEAN is a framework that provides a easy starting point for MongoDB, Node.js, Express, and AngularJS based applications. It is designed to give you a quick and organized way to start developing MEAN based web apps with useful modules like Mongoose and Passport pre-bundled and configured. We mainly try to take care of the connection points between existing popular frameworks and solve common integration problems.

Prerequisites

• MongoDB - Download and Install mongodb - Checkout their manual if you're just starting.
• Node.js - Download and Iמstall Node.js, codeschool has free node and angular tutorials.
• Git - Get git using a package manager or download it.
• Grunt - Download and Install Grunt.

$ npm install -g grunt-cli

Installation

To start with MEAN install the mean-cli package from NPM. This will add the mean command which lets you interact (install, manage, update ...) your mean based application.

Install the MEAN CLI

  $ sudo npm install -g mean-cli
  $ mean init <myApp>
  $ cd <myApp> && npm install

Invoke node with Grunt

We recommend using Grunt to start the server:

  $ grunt

If grunt aborts because of JSHINT errors, these can be overridden with the force flag:

  $ grunt -f

Alternatively, when not using grunt (and for production environments) you can run:

  $ node server

Then, open a browser and go to:

  http://localhost:3000

Troubleshooting

During installation depending on your os and prerequiste versions you may encounter some issues.

Most issues can be solved by one of the following tips, but if are unable to find a solution feel free to contact us via the repository issue tracker or the links provided below.

Update NPM, Bower or Grunt

Sometimes you may find there is a weird error during install like npm's Error: ENOENT. Usually updating those tools to the latest version solves the issue.

• Updating NPM:

$ npm update -g npm

• Updating Grunt:

$ npm update -g grunt-cli

• Updating Bower:

$ npm update -g bower

Cleaning NPM and Bower cache

NPM and Bower has a caching system for holding packages that you already installed. We found that often cleaning the cache solves some troubles this system creates.

• NPM Clean Cache:

$ npm cache clean

• Bower Clean Cache:

$ bower cache clean

Installation problems on Windows 8 / 8.1

Some of Mean.io dependencies uses node-gyp with supported Python version 2.7.x. So if you see an error related to node-gyp rebuild follow next steps:

1. install Python 2.7.x
2. install Microsoft Visual Studio C++ 2012 Express
3. Run NPM update

$ npm update -g

Technologies

The MEAN stack

MEAN is an acronym for Mongo, Express.js , Angular.js and N ode.js

MongoDB

Go through MongoDB Official Website and proceed to its Great Manual, which should help you understand NoSQL and MongoDB better.

Express

The best way to understand express is through its Official Website, particularly The Express Guide; you can also go through this StackOverflow Thread for more resources.

AngularJS

Angular's Official Website is a great starting point. CodeSchool and google created a great tutorial for beginners., and the angular videos by Egghead.

Node.js

Start by going through Node.js Official Website and this StackOverflow Thread, which should get you going with the Node.js platform in no time.

Additional Tools

• Mongoose - The mongodb node.js driver in charge of providing elegant mongodb object modeling for node.js
• Passport - An authentication middleware for Node.js which supports authentication using a username and password, Facebook, Twitter, and more.
• Twitter Bootstrap - The most popular HTML, CSS, and JS framework for developing responsive, mobile first projects.
• UI Bootstrap - Bootstrap components written in pure AngularJS

CLI

Overview

The MEAN CLI is a simple Command Line Interface for installing and managing MEAN applications. As a core module of the mean.io project, it provides a number of useful tools to make interaction with your MEAN application easier, with features such as: scaffolding, module creation and admin, status checks, and user management.

  $ mean
  $ mean --help
  $ mean help

mean help can also be used in conjunction with any command to get more information about that particular functionality. For example, try mean help init to see the options for init

  $ mean help [command]

Users

Information can be display for a specific customer via mean user email. Email is required. User roles can be assigned or removed with the --addRole (or -a) and --removeRole (or -r) options, respectively.

For example, the admin role is required to edit tokens.

```bash $ mean user $ mean user --addRole ; $ mean user --removeRole ; ```

packages

Management

All of the remaining of the commands must be run from the root folder of your MEAN application.

Contributed MEAN packages can be installed or uninstalled via the CLI. Also, currently installed modules can be viewed with the list command.

```bash $ mean list $ mean install <module> $ mean uninstall <module> ```

Mean packages installed via the installer are found in /node_modules

#### Search To find new packages run the *mean search* command ```bash $ mean search [packagename] ``` mean search will return all of the available packages, mean search packagename will filter the search results.

Scaffolding

To create a new MEAN app, run mean init. Name for the application is optional. If no name is provided, "mean" is used. The MEAN project will be cloned from GitHub into a directory of the application name.

  $ mean init [name]
  $ cd [name] && npm install

Note: git must be installed for this command to work properly.

Misc

Status

Check the database connection for a particular environment (e.g. development (default), test, production) and make sure that the meanio command line version is up to date.

```bash $ mean status ```

Docs

A simple shortcut to open the mean documentation in your default browser.

```bash $ mean docs ```

Packages

Everything in mean.io is a package and when extending mean with custom functionality make sure you create your own package and do not alter the core packages.

Core Packages

System

coming soon

Users

coming soon

Access

coming soon

Theme

coming soon

Articles

coming soon

Files structure

coming soon

Creating your own package

To create your own package and scaffold it's initial code - run

mean package <packageName>

This will create a package under /packages/custom/pkgName

Contributing you package

Config

All the configuration is specified in the config folder, through the env files, and is orchestrated through the meanio NPM module. Here you will need to specify your application name, database name, and hook up any social app keys if you want integration with Twitter, Facebook, GitHub, or Google.

Environmental Settings

There is a shared environment config: all

• root - This the default root path for the application.
• port - DEPRECATED to http.port or https.port.
• http.port - This sets the default application port.
• https - These settings are for running HTTPS / SSL for a secure application.
• port - This sets the default application port for HTTPS / SSL. If HTTPS is not used then is value is to be set to false which is the default setting. If HTTPS is to be used the standard HTTPS port is 443.
• ssl.key - The path to public key.
• ssl.cert - The path to certificate.

There are three environments provided by default: development, test, and production. Each of these environments has the following configuration options:

• db - This is where you specify the MongoDB / Mongoose settings
• url - This is the url/name of the MongoDB database to use, and is set by default to mean-dev for the development environment.
• debug - Setting this option to true will log the output all Mongoose executed collection methods to your console. The default is set to true for the development environment.
• options - These are the database options that will be passed directly to mongoose.connect in the production environment: [server, replset, user, pass, auth, mongos] (http://mongoosejs.com/docs/connections.html#options) or read [this] (http://mongodb.github.io/node-mongodb-native/driver-articles/mongoclient.html#mongoclient-connect-options) for more information.
• app.name - This is the name of your app or website, and can be different for each environment. You can tell which environment you are running by looking at the TITLE attribute that your app generates.
• Social OAuth Keys - Facebook, GitHub, Google, Twitter. You can specify your own social application keys here for each platform:
  • clientID
  • clientSecret
  • callbackURL
• emailFrom - This is the from email address displayed when sending an email.
• mailer - This is where you enter your email service provider, username and password.

To run with a different environment, just specify NODE_ENV as you call grunt:

    $ NODE_ENV=test grunt

If you are using node instead of grunt, it is very similar:

    $ NODE_ENV=test node server

To simply run tests

    $ npm test

NOTE: Running Node.js applications in the production environment enables caching, which is disabled by default in all other environments.

Staying up to date

After initializing a project, you'll see that the root directory of your project is already a git repository. MEAN uses git to download and update its own code. To handle its own operations, MEAN creates a remote called upstream. This way you can use git as you would in any other project.

To maintain your own public or private repository, add your repository as remote. See here for information on adding an existing project to GitHub.

git remote add origin <remote repository URL>
git push -u origin master

Hosting MEAN

Heroku

Before you start make sure you have the Heroku toolbelt installed and an accessible MongoDB instance - you can try MongoHQ which has an easy setup).

Add the db string to the production env in server/config/env/production.js.

git init
git add .
git commit -m "initial version"
heroku apps:create
heroku config:add NODE_ENV=production
heroku config:add BUILDPACK_URL=https://github.com/mbuchetics/heroku-buildpack-nodejs-grunt.git
git push heroku master
heroku config:set NODE_ENV=production

OpenShift

1. Register for an account on Openshift (http://www.openshift.com).
2. Create an app on Openshift by choosing a 'Node' type site to create. Create the site by making Openshift use Linnovate's Openshift git repo as its source code (https://github.com/linnovate/mean-on-openshift.git)
3. On the second screen after the new application has been created, add a Mongo database
4. When the site has been built, you can visit it on your newly created domain, which will look like my-domain.openshift.com. You may need to restart the instance on Openshift before you can see it. It will look like Mean.io boilerplate.
5. On your new app's console page on Openshift, make a note of the git repo where the code lives. Clone that repo to your local computer where your mean.io app codebase is.
6. Merge your completed local app into this new repo. You will have some conflicts, so merge carefully, line by line.
7. Commit and push the repo with the Openshift code back up to Openshift. Restart your instance on Openshift, you should see your site!

More Information

• Visit us at Linnovate.net.
• Visit our Ninja's Zone for extended support.

Cedits

• Valeri Karpov for coining the term mean and triggering the mean stack movement.
• Amos Haviv for the creation of the initial version of mean.io while working for us @linnovate.
• Madhusudhan Srinivasa which inspired us with his great work.

License

We belive that mean should be free and easy to integrate within your existing projects so we chose the The MIT License