MEAN Stack

MEAN is a framework for an easy starting point with 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.

Prerequisite Technologies

Linux

• Node.js - Download and Install Node.js, nodeschool has free node tutorials to get you started. We recommend node-4.x as the preferred node version to run mean.io.
• MongoDB - Download and Install mongodb - Checkout their manual if you're just starting.

If you're using ubuntu, this is the preferred repository to use...

$ curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
$ sudo apt-get update
$ sudo apt-get install nodejs

• Git - Get git using a package manager or download it.

Windows

• Node.js - Download and Install Node.js, nodeschool has free node tutorials to get you started.
• MongoDB - Follow the great tutorial from the mongodb site - "Install Mongodb On Windows"
• Git - The easiest way to install git and then run the rest of the commands through the git bash application (via command prompt) is by downloading and installing Git for Windows

OSX

• Node.js - Download and Install Node.js or use the packages within brew or macports.
• MongoDB - Follow the tutorial here - Install mongodb on OSX
• git - Get git from here.

Prerequisite packages

• Mean currently uses gulp as a build tool and bower to manage frontend packages.

$ npm install -g gulp
// and bower
$ npm install -g bower

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

In linux install in globally as root

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

Invoke node with a task manager

Mean supports the gulp task runner for various services which are applied on the code. To start your application run -

$ gulp

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

$ node server

Then, open a browser and go to:

http://localhost:3000

Running on a different port

If you have a rails, node, or other mean project already running, you may need to use a different port. You can set the port and start your new mean project with one command:

$ export PORT=3001 && gulp

Then, open a browser and change the port number before you visit:

  http://localhost:3001

Troubleshooting

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

Most issues can be solved by one of the following tips, but if you 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 Gulp

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 Gulp:

$ npm update -g gulp

• 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

Git "not found" on Windows

If you get this error when trying to mean init:

Prerequisite not installed: git

And you definitely have Git for Windows installed, then it's not included in your path. Find the folder containing git.exe (likely C:\Program Files (x86)\Git\cmd) and add it to your PATH.

Technologies

The MEAN stack

MEAN is an acronym for Mongo, Express.js , Angular.js and Node.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 the documentation page as well as 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.

  $ mean user <email>
  $ mean user <email> --addRole <role>;
  $ mean user <email> --removeRole <role>;

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.

$ 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

$ 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.

$ mean status

Docs

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

$ 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.

The mean.io package system allows developers to create modular code that provides useful tools that other mean developers can use. The packages, when published, are plug-and-play and are used in a way very similar to traditional npm packages.

The mean.io package system integrates all the packages into the mean project as if the code was part of mean itself and provides the developers with all the necessary tools required to integrate their package into the host project.

There are two types of packages:

Custom Packages are generated by the mean scaffolder and contain most of your application logic. Custom packages are found in /packages/custom and can be published as a contrib package for use by other developers.

Contrib Packages are installed by the mean installer and are found at /packages/contrib. Contrib packages are "plug and play".

Core Packages

All Core packages can be overridden by other packages allowing you to extend and adapt it to fit your specific needs. See Overriding views for detailed examples.

System

The "system" package creates the basic pages as well as defines the layout of the site and integrates the menu into the page. The system package also allows us to define things such as rendering engines, static files and routing on the client and server side.

Users

The "users" package creates the database model of the user, provides validation as well as various login and registration features.

Access

The "access" package manages permissions and middleware. It controls the various authentication methods and is dependent on the users package

Theme

The "theme" package adds some basic CSS and other assets such as images and backgrounds

Articles

The "articles" package is typically used as an example starting point for managing content that might be used in a blog or cms. The full CRUD is implemented on the server and client.

File structure

The file structure is similar to that of the mean project itself

Fundamental Files at the root of the package

Server

Packages are registered in the app.js Defines package name, version and mean=true in the package.json

All of the Server side code resides in the /server directory.

Server
--- config        # Configuration files
--- controllers   # Server side logic goes here
--- models        # Database Schema Models
--- routes        # Rest api endpoints for routing
--- views         # Swig based html rendering

Client

All of the Client side code resides in the /public directory.

public
--- assets        # JavaScript/CSS/Images (not aggregated)
--- controllers   # Angular controllers
--- config        # Contains routing files
--- services      # Angular services (also directive and filter folders)
--- views         # Angular views

All JavaScript within public is automatically aggregated with the exception of files in public/assets, which can be manually added using the aggregateAsset() function.

Files within the public directory of the package can be accessed externally at /[package-name]/path-to-file-relative-to-public. For example, to access the Tokens Angular controller, tokens/controllers/tokens.js.

Registering a Package

In order for a Package to work it needs to be registered. By doing this you make the package system aware that you are ready and that other packages are able to depend on you. The packages are