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.
- 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
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.
$ sudo npm install -g mean-cli
$ mean init <myApp>
$ cd <myApp> && npm install
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
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.
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
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
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:
- install Python 2.7.x
- install Microsoft Visual Studio C++ 2012 Express
- Run NPM update
$ npm update -g
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.
- 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
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]
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 ; ```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 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.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.
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 ```A simple shortcut to open the mean documentation in your default browser.
```bash $ mean docs ```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 meanio 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 necceesary 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".
All Core
packages can be overridden by other packages allowing you to extend and adapt it to fit your specific needs. See overriding core packages
for detailed examples
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.
The users package creates the database model of the user, provides validation as well as various login and registration features.
The access package managers permissions and middleware. It controls the various authentication methods and is dependent on the users package
The theme package adds some basic CSS and other assets such as images and backgrounds
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.
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 assets which can be manually added using the aggregateAsset()
function
Files within public of the package can be accessed externally /[package-name]/path-to-file-relative-to-public
for example to access 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 package system aware that you are ready and that other packages are able to depend on you. The packages are registered from within app.js
When registering you are required to declare all your dependencies in order for the package system to make them available to your package.
// Example of registering the MyPackage
MyPackage.register(function(app, auth, database) {
});
MEAN has 3 pre registered dependencies. app
which makes the express app available auth
which has some basic authentication functions and database
which contains the mongoose database connection.<
All dependencies specified must be registered in order to use them
###Dependency Injection
An injection is the passing of a dependency (a service) to a dependent object (a client). The service is made part of the client's state. Passing the service to the client, rather than allowing a client to build or find the service, is the fundamental requirement of the pattern. Wikipedia
Dependency injection allows you to declare what dependencies you require and rely on the package system to resolve all dependencies for you. Any package registered is automatically made available to anyone who would like to depend on them.
Looking again at the registration example we can see that MyPackage
depends on the Tokens
and can make use of it full functionality including overriding it.
// Example of registering the tokens package
MyPackage.register(function(app, auth, database, Tokens) {
//I can make use of the tokens within my module
MyPackage.someExampleFunction('some paramater');
//I can override functions
MyPackage.someExampleFunction = function(param) {
//my custom logic goes here
};
});
Packages when in code are used in a capitalized form
###Angular Modules and Dependencies
Every package registration automatically creates a corresponding angular module of the form mean.[package-name]
The package system injects this information into the mean init functions and allows developers to base their controllers, services, filters, directives etc on either an existing module or on their own one.
In addition you are able to declare which angular dependencies you want your angular module to use.
Below is an example of adding an angular dependency to our angular module.
// Example of adding an angular dependency of the ngDragDrop to the
MyPackage.angularDependencies(['ngDragDrop']);
See the assets section for an example how to add external libraries to the client such as the
gDragDrop
javascript library
###Assets and Aggregation
All assets such as images, javascript libraries and css stylesheets should be within public/assets
of the package file structure.
Javascript and css from assets
can be aggregated to the global aggregation files. By default all javascript is automatically wrapped within an anonymous function unless given the option {global:true}
to not enclose the javascript within a contained scope
//Adding jquery to the mean project
MyPackage.aggregateAsset('js','jquery.min.js');
//Adding another library - global by default is false
MyPackage.aggregateAsset('js','jquery.min.js', {global:true});
//Adding some css to the mean project
MyPackage.aggregateAsset('css','default.css');
Javascript files outside of assets are automatically aggregated and injected into the mean project. As a result libraries that you do not want aggregated should be placed within
public/assets/js
###Settings Object The settings object is a persistance object that is stored in the packages collection and allows for saving persistant information per package such as configuration options or admin settings for the package.
Receives two arguments the first being the settings object the second is a callback function
MyPackage.settings({'someSetting':'some value'},function (err, settings) {
//you will receive the settings object on success
});
// Another save settings example this time with no callback
// This writes over the last settings.
MyPackage.settings({'anotherSettings':'some value'});
// Get settings. Retrieves latest saved settigns
MyPackage.settings(function (err, settings) {
//you now have the settings object
});
Each time you save settings you overwrite your previous value. Settings are designed to be used to store basic configuration options and should not be used as a large data store
###Express Routes
All routing to server side controllers is handled by express routes. The package system uses the typical express approach. The package system has a route function that passes along the package object to the main routing file typically server/routes/index.js
By default the Package Object is passed to the routes along withe the other arguments MyPackage.routes(app, auth, database);
Example from the server/routes/index.js
// The Package is past automatically as first parameter
module.exports = function(MyPackage, app, auth, database) {
//example route
app.get('/myPackage/example/anyone', function (req,res,next) {
res.send('Anyone can access this');
});
};
###Angular Routes
The angular routes are defined in public/config/routes
. Just like the latest version of mean, the packages use the $stateProvider
$stateProvider
.state('myPackage example page', {
url: '/myPackage/example',
templateUrl: 'myPackage/views/index.html'
});
The angular views are publically accessible via templateUrl when prefixed with the package name
###Menu System
Packages are able to hook into an existing menu system and add links to various menus integrated within mean.
Each link specifies its title
, template
, menu
and role
that is allowed to see the link. If the menu specified does not exist a new menu will be created. The menu object is made accessible within the client by means of a menu angular service that queries the menu controller for information about links.
Below is an example how to add a link to the main menu from app.js
//We are adding a link to the main menu for all authenticated users
MyPackage.menus.add({
title: "myPackage example page",
link: "myPackage example page",
roles: ["authenticated"],
menu: "main"
});
You can look at the angular header controller in the mean project for more info. You can find it
public/system/controllers/header.js
and see how the menu service is implemented
###Html View Rendering
The packages come built in with a rendering function allowing packages to render static html. The default templating engine is swig. The views are found in server/views
of the package and should end with the .html suffix
Below is an example rendering some simple html>
app.get('/myPackage/example/render', function (req,res,next) { MyPackage.render('index', {packageName:'myPackage'}, function (err, html) { //Rendering a view from the Package server/views res.send(html); }); });
###Overriding the default views and layouts One is able to override the default layout of the application through a custom package.
Below is an example overriding the default layout of system and instead using the layourts found locally within the package
MyPackage.register(function(system, app) {
app.set('views', __dirname + '/server/views');
Please note that the package must depend on
System
to ensure it is evaluated afterSystem
and can thus override the views folder
To create your own package and scaffold it's initial code - run
mean package <packageName>
This will create a package under /packages/custom/pkgName
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.
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.
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
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
- Register for an account on Openshift (http://www.openshift.com).
- 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)
- On the second screen after the new application has been created, add a Mongo database
- 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.
- 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.
- Merge your completed local app into this new repo. You will have some conflicts, so merge carefully, line by line.
- Commit and push the repo with the Openshift code back up to Openshift. Restart your instance on Openshift, you should see your site!
- Visit us at Linnovate.net.
- Visit our Ninja's Zone for extended support.
- To our awesome core team with help of our contributors which have made this project a success.
- 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.
We belive that mean should be free and easy to integrate within your existing projects so we chose the The MIT License