_      _    _____   _   _       ____   _____   _____        ____   _____  _____  ____
      / \ /\ / \  /__ __\ / \ / \__/| /  _ \ /__ __\ /  __/       / ___\ /  __/ /  __/ /  _ \
      | | || | |    / \   | | | |\/|| | / \ |  / \   |  \  _____  |    \ |  \   |  \   | | \|
      | \_/| | |_/\ | |   | | | |  || | |-| |  | |   |  /_ \____\ \___ | |  /_  |  /_  | |_/|
      \____/ \____/ \_/   \_/ \_/  \| \_/ \ |  \_/   \____\       \____/ \____\ \____\ \____/

Demo hosted on Heroku

ultimate-seed is the ultimate full-stack AngularJS + Node.js/Express seed (batteries included!) that makes web developers insanely productive.

This project uses ultimate dependency library.

Batteries Included

ultimate-seed comes with many of popular, battle-tested modern web frameworks and libraries. All these parts are already wired together for you using best practices! :) Don't waste time writing boilerplate code.

• Angular
• AngularUI
• Bootstrap
• Bower
• Browserify
• Express
• Font Awesome
• Grunt
• Handlebars
• jQuery
• JSHint
• Karma w/ Mocha
• LESS w/ LESS Hat
• Livereload
• Lodash (Underscore)
• Modernizr
• MongoDB w/ Mongoose
• Passport
• Passport-Facebook
• Passport-Google
• Passport-Twitter
• Redis w/ Hiredis
• SocketIO
• Source Maps
• Uglify
• Winston

How to Use

Dependencies

Dependency	Installation
Node.js	download
MongoDB	download
Redis	download
Bower	npm install bower -g
Grunt	npm install grunt-cli -g

Make sure both MongoDB and Redis servers running somewhere. (You can use free hosting services such as MongoHQ or MongoLab for MongoDB and Redis To Go or RedisCloud for Redis.) Then, update configuration information in config/{development,heroku,production}.json.

If you find any reason not to use Redis in your project, you can easily achieve it by following this instruction:

1. Change the value of session.store._use to mongo in config/{development,heroku,production}.json. (This lets ultimate-seed use MongoDB as session backend.)
2. Comment out the line ultimate.db.redis.connect(app.config.db.redis); in server/app.js. (This prevents server connecting to Redis server.)

Installation

Method 1: Yeoman Generator

Yeoman generator for ultimate-seed can be used to clone the seed project.

$ npm install -g yo
$ npm install -g generator-ultimate
$ yo ultimate
$ npm install && bower install

Method 2: Git Clone

Download ultimate-seed and install dependency modules:

$ git clone https://github.com/pilwon/ultimate-seed.git ultimate-seed
$ cd ultimate-seed
$ npm install && bower install

Method 3: Git Branch Tracking Remote

Now create seed branch that tracks remote branch ultimate-seed/master:

$ git remote add seed https://github.com/pilwon/ultimate-seed.git
$ git fetch seed
$ git checkout -b seed seed/master

Push a copy of seed to origin/seed:

$ git push origin seed

Merge seed to master branch:

$ git checkout master
$ git merge seed
$ npm install && bower install

Resolve merge conflicts then push to origin/master:

$ git push

Development (config/development.json)

Grunt tasks to build your app:

$ grunt                    # start server
$ grunt build              # jshint & build
$ grunt clean              # clean grenerated files

• If you see the Could not load the bindings file. error message, please perform npm rebuild then try again.

Deployment

Production Server (config/production.json)

First, prepare and optimize all files used in production environment:

$ grunt build

Then your app can be started in production mode using this command:

$ NODE_ENV=production node server

It is recommended to use a tool like forever to ensure your app running continuously:

$ npm install forever -g
$ NODE_ENV=production PORT=3000 forever start server

You can alternatively use a system-wide process control system such as Supervisor with the following configuration (supervisord.conf):

[program:ultimate-3000]
directory = <absolute-path-of-project-root>
environment = NODE_ENV=production, PORT=3000
command = node server
autostart = true
autorestart = true

Heroku (config/heroku.json)

ultimate-seed supports deployment of your app to Heroku servers.

1. Modify config/heroku.json.
2. Comment out the following lines in .gitignore. * /.cachebust * /client/js/node_modules/bower_components/ * /client-built/ * /config/heroku.json * /node_modules/
3. Run grunt build to build the project.
4. Commit all files to a local git repository created at the project root.
5. Add git remote pointing to Heroku: * New Heroku app: heroku create APPID * Existing Heroku app: heroku git:remote -a APPID
6. Set the environment variable: heroku config:set NODE_ENV=heroku ERROR_PAGE_URL=http://APPID.herokuapp.com/404.html
7. Enable websocket support: heroku labs:enable websockets
8. (Optional) Install MongoDB and Redis add-ons to the Heroku app. ultimate-seed reads environment variables attached by these add-ons. (Note: Add-on environment variables will override MongoDB/Redis configuration values in config/heroku.json): * Mongo: heroku addons:add mongohq:sandbox or heroku addons:add mongolab:sandbox * Redis: heroku addons:add redistogo:nano or heroku addons:add rediscloud:20
9. Deploy application to Heroku using git push heroku +master
10. Deployed at http://APPID.herokuapp.com/

Using REPL (read-eval-print loop)

This is helpful when you need to debug problems on the production server. You can connect to REPL of the running server via UNIX socket. By default, it creates UNIX socket at /tmp/ultimate-repl but you can configure it in config/{development,heroku,production}.json. In order to connect to it, simply run:

$ nc -U /tmp/ultimate-repl
ultimate>

or if you want readline's line editing and persistent history (i.e. using up/down arrow key to see the command history), then install rlwrap (on Mac, brew install rlwrap) and run:

$ rlwrap nc -U /tmp/ultimate-repl
ultimate>

Once you are connected, you can evaluate Javascript expression.

ultimate> 3 + 3
6
ultimate>

For your convenience, several variables/functions are exposed. Try the followings:

ultimate> app  // ultimate app object
ultimate> ld  // lodash (underscore) object (couldn't use _ because it has special meaning in REPL i.e. the result of the last expression)
ultimate> ultimate  // ultimate object that ultimate-seed utilizes
ultimate> showRoutes()  // shows an array of all routes (e.g. [ ..., 'GET /api/user/features/:id', ...])

Directory Structure

.
├── client/
│   ├── components/
│   ├── fonts/
│   │   ├── font-awesome/
│   │   └── glyphicons/
│   ├── js/
│   │   ├── {{module}}/
│   │   │   ├── controllers/
│   │   │   ├── directives/
│   │   │   ├── services/
│   │   │   ├── templates/
│   │   │   │   └── {{template}}.html
│   │   │   └── index.js
│   │   ├── node_modules/
│   │   │   ├── bower_components/
│   │   │   └── custom_components/
│   │   ├── app.js
│   │   └── index.js
│   └── less/
│       ├── _layouts/
│       ├── bootstrap/
│       ├── font-awesome/
│       ├── lesshat/
│       └── social-buttons/
├── config/
│   ├── development.json
│   ├── heroku.json
│   ├── nginx.conf
│   └── production.json
├── log/
├── node_modules/
├── server/
│   ├── controllers/
│   ├── lib/
│   ├── models/
│   ├── sockets/
│   ├── views/
│   │   ├── _helpers/
│   │   ├── _layouts/
│   │   │   └── default.hbs
│   │   ├── _partials/
│   │   │   └── livereload.hbs
│   │   ├── home/
│   │   ├── status/
│   │   └── empty.hbs
│   ├── app.js
│   ├── index.js
│   ├── routes.js
│   ├── socketio.js
│   └── winston.js
├── static/
│   ├── img/
│   ├── 404.html
│   ├── favicon.ico
│   └── robots.txt
├── .bowerrc
├── .editorconfig
├── .jshintrc
├── .slugignore
├── Gruntfile.js
├── Procfile
├── bower.json
├── npm-scripts.js
├── package.json
└── project.json

Contributing to the Project

We welcome your pull requests to the dev branch.

Credits

• Pilwon Huh (creator, maintainer)
• Brian Park (collaborator)

Thanks to all the other contributors as well! :)

License

The MIT License (MIT)

Copyright (c) 2012-2013 Pilwon Huh

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.