Last updated: 14 Jul 2015.
Thank you for downloading the MEAN.JS boilerplate!

This simple documentation will cover the basics of developing your MEAN application.

Before you begin we recommend you read about the basic building blocks that assemble a MEAN.JS application:

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. You can also use Thinkster Popular Guide, and the Egghead Videos.
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.
When you're done with those resources and feel you understand the basic principals continue to other sections.

Enjoy & keep us updated,
The MEAN.JS Team.

In this section you'll learn how to get started with a MEAN.JS application, install all the prerequisites, and initialize your application.

Prerequisites

Before you begin, you should make sure you have installed all these prerequisites on your development machine.


Node.js & npm
Download & Install Node.js and the npm package manager, if you encounter any problems, you can also use this Github Gist to install Node.js.
MongoDB
Download & Install MongoDB, and make sure it's running on the default port (27017).
Bower
You're going to use the Bower Package Manager to manage your front-end packages, in order to install it make sure you've installed Node.js and npm, then install bower globally using npm:
$ npm install -g bower
Grunt
You're going to use the Grunt Task Runner to automate your development process, in order to install it make sure you've installed Node.js and npm, then install grunt globally using npm:
$ npm install -g grunt-cli

Note: Your user might not have the permissions to install package globally, so use a super user or sudo.

Downloading MEAN.JS

There are several ways you can get the MEAN.JS boilerplate:

Yo Generator

The generator is still in development. See the Generator Repo for information on how to use the development version.

Note: If you want to support git mergeupdates it would be better to use git clonefor your initial project creation, don't worry you'd still be able use the generator.

Cloning The GitHub Repository

You can also use Git to directly clone the MEAN.JS repository and switching to the 0.4.0 branch:

$ git clone https://github.com/meanjs/mean.git meanjs
$ git checkout 0.4.0

This will clone the latest version of the MEAN.JS repository to a meanjs folder.

Downloading The Repository Zip File

Another way to use the MEAN.JS boilerplate is to download a zip copy from the master branch on github. You can also do this using wget command:

$ wget https://github.com/meanjs/mean/archive/0.4.0.zip -O meanjs.zip; unzip meanjs.zip; rm meanjs.zip

Don't forget to rename mean-0.4.0 after your project name.

Quick Install

Once you've installed all the prerequisites, you're just a few steps away from starting to develop you MEAN application.

The first thing you should do is install the Node.js dependencies. The boilerplate comes pre-bundled with a package.json file that contains the list of modules you need to start your application, to learn more about the modules installed visit the NPM & Package.json section.

To install Node.js dependencies you're going to use npm again, just run this in the command-line:

$ npm install

This command does a few things:
  • First it will install the dependencies needed for the application to run.
  • If you're running in a development environment, it will then also install development dependencies needed for testing and running your application.
  • Finally, when the install process is over, npm will initiate a bower installcommand to install all the front-end modules needed for the application.

Running Your Application

After the install process is over, you'll be able to run your application using Grunt, just run grunt default task:

$ grunt
Your application should run on the 3000 port so in your browser just go to http://localhost:3000.

That's it! your application should be running by now, to proceed with your development check the other sections in this documentation.
If you encounter any problem try the Troubleshooting section.

Configuring Social Services

MEAN.JS allows you to login via a number of social services. In other deployments of MEAN.JS you need to configure environment variables with the various keys and secrets to enable these social services. While this is possible in Cloud Foundry, it is not the preferred method. Credentials like this are usually surfaced through services an application can bind to. For this reason, when you deploy MEAN.JS to Cloud Foundry you must configure and bind services to your application in order to login with the various social services. To do this we will use what is called user provided services.

Once your application is deployed to Cloud Foundry run the following command for the social services you would like to use. Make sure you insert the correct credentials for the service.

Facebook

    $ cf cups mean-facebook -p '{"id":"facebookId","secret":"facebookSecret"}'
    $ cf bind-service mean mean-facebook
  

Twitter

    $ cf cups mean-twitter -p '{"key":"twitterKey","secret":"twitterSecret"}'
    $ cf bind-service mean mean-twitter
  

Google

    $ cf cups mean-google -p '{"id":"googleId","secret":"googleSecret"}'
    $ cf bind-service mean mean-google
  

LinkedIn

    $ cf cups mean-linkedin -p '{"id":"linkedinId","secret":"linkedinSecret"}'
    $ cf bind-service mean mean-linkedin
  

GitHub

    $ cf cups mean-github -p '{"id":"githubId","secret":"githubSecret"}'
    $ cf bind-service mean mean-github
  

Email

    $ cf cups mean-mail -p '{"from":"fromEmail","service":"emailService","username":"emailServiceUsername",
    "password":"emailServicePassword"}'
    $ cf bind-service mean mean-mail
  

After you have bound the services your want to your MEAN.JS application run

$ cf restage mean
to restage your application and your social services should now work.

Cloud Foundry Troubleshooting

Every time I deploy my application to Cloud Foundry a new route gets added, why? How do I fix this?

No two apps deployed to a Cloud Foundry instance can have the same URL or route bound to it. To avoid failures during deployment where two people try to deploy MEANJS to the same Cloud Foundry instance using the same URL, the `manifest.yml` file in the root directory of MEANJS contains a host property specifying that Cloud Foundry assign a random URL to your application. This URL will begin with the prefix 'mean-' and end with a random word. If you perform multiple `cf push` commands Cloud Foundry will bind a new random URL or route to your application each time. This means you end up with multiple URLs pointing to the same application instance. While this does not hurt your application it is generally not necessary. You can fix this by changing the host property in your `manifest.yml` file to remove the `${random-word}` string from it. However note that if your host name is not unique, your deployment will fail. If it does fail try changing the host property to something else.

During the installation process you may encounter some problems, so what can you do?

Check Node.js and npm Versions

The rapid advancements in JavaScript modules can sometimes cause version issues with the MEAN's dependencies. We try to keep up with the stable versions, and make sure the modules versions are compatible with those versions. We can't control the pre-installed platforms versions, so make sure you didn't install unsupported versions of Node.js and MongoDB.

MongoDB
MongoDB version 2.4.x is supported.
Node.js
Node version 0.10.x is supported.
npm
npm version 1.3.x is supported.

Update npm, Bower or Grunt

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 (Unix/Linux)
To update npm just run this command in the command-line:
$ npm update -g npm
Updating npm (Windows)

There is a known issue with npm 1.x which is installed by default with the latest version of NodeJS. If you experience file locks during the "npm install" step, please refer here.

Updating Bower
To update bower just run this command in the command-line:
$ npm update -g bower
Updating Grunt
To update grunt just run this command in the command-line:
$ npm update -g grunt-cli

Cleaning npm and Bower cache

Both npm and Bower uses a caching system that caches the packages you already installed. Often cleaning npm & Bower's cache can solve some of the issues you encounter during the installation process.

Cleaning npm's cache
To clean npm's cache just run this command in the command-line:
$ npm cache clean
Cleaning Bower's cache
To clean bower's cache just run this command in the command-line:
$ bower cache clean

Common Issues

There are some common errors while installing mean:

Node is running but AgnularJS application won't load
Check to see all your front-end packages were installed. Bower package manager is used to install the front-end package and it will need a .bowerrc file to install the packages in the right location.
Bower should install the packages in the public/lib folder, so if this folder or some of its sub-folders doesn't exist, run:
$ bower update
This will install the missing packages.
Error: failed to connect to [localhost:27017]
If you use a local MongoDB check to see if its running. In case you use an external service verify the URI in the configuration files.

Sometimes it can be a local issue or something that we didn't cover, in case you have any further questions please contact us via the community page.