Setting up Habitica Locally

First steps to start development for HabitRPG include setting up the code locally. This way, a developer can test changes directly before contributing them to the main repository.

Vagrant
Vagrant is a system to create reproducible and portable development environments. Because of the variety of systems used for HabitRPG development and the various issues developers may encounter setting up HabitRPG on them, Vagrant provides a single development environment with minimal dependencies on the developer's local platform. Setting HabitRPG up via this section's instructions is not a pre-requisite for the Unix/Windows sections, but an alternative.

You can use Vagrant on a variety of systems including Windows, Mac OS X, and Linux.

To use Vagrant, go to their downloads page and download and install the software appropriate for your system. On Mac OS, you will also need to install the free virtual machine software VirtualBox.

The process below uses a Vagrant box from vagrantcloud.com. The box will be automatically fetched if your version of Vagrant is recent enough (The current Vagrant environment requires a minimum of Vagrant version 1.5). If you receive errors such as "The box 'thepeopleseason/habitrpg' could not be found" then upgrade Vagrant to the latest version.

Once Vagrant has been installed, use the following instructions to get the environment up and running:


 * 1) Follow steps 1-3 in Fork &amp; Clone HabitRPG (fork & clone, setup upstream branch, and rebase branch).
 * 2) Create a config file from the example one: cp config.json.example config.json
 * 3) Edit config.json with your values for ADMIN_EMAIL, SMTP_USER, SMTP_PASS, and SMTP_SERVICE
 * 4) Boot up the box: vagrant up
 * 5) Login to the environment: vagrant ssh
 * 6) Start the system: npm start
 * 7) Open a browser to http://localhost:3000 to test the application!

Note: If you encountered an error message at the end of your invocation of 'vagrant up,' you may need to run the following before 'npm start': bower install -f A forthcoming code update should eliminate the need for this step.

You'll be logged into an Ubuntu Linux virtual machine. For more options, check the VAGRANT.md file in the root of your cloned HabitRPG repo.

If you wish to help with unit testing, you will also need to run: sudo apt-get install openjdk-7-jre curl on the vagrant machine.

Unix
Blacksmiths running Linux, Mac OSX, or other flavors of Unix should follow these instructions. Windows users should skip this section and read the one below with Windows-specific steps.


 * 1) Install and set up MongoDB - see also  Guidance for Blacksmiths: MongoDB
 * 2) Install and set up NodeJS (and npm) - see also Angular/Node/Jade Tips &amp; Best Practices. Because Ubuntu's software repositories may run a few months behind the latest revisions, Ubuntu users will want to install node from an updated repository : apt-get update  apt-get install python-software-properties  apt-add-repository ppa:chris-lea/node.js  apt-get update  apt-get install nodejs
 * 3) Install and set up Git - see also Guidance for Blacksmiths: Git
 * 4) Fork the repository on your computer - refer to Fork &amp; Clone HabitRPG and/or GitHub's Fork A Repo
 * 5) Make sure you are on the develop branch before starting work; this should be the default branch if you are forking from github. You can check with git branch. The branch with a star next to it is the branch you are currently on. If you are not on the develop branch, switch to it git checkout develop
 * 6) Install grunt-cli npm package globally (on some systems you may need to add sudo in front of this command): npm install -g grunt-cli bower
 * 7) Install the npm and bower packages: npm install
 * 8) For OS X, you may need to install bower separately. If you get a fatal error in the previous step, try: bower install  sudo npm install
 * 9) Create a config file from the example one: cp config.json.example config.json
 * 10) Edit config.json with your values for ADMIN_EMAIL, SMTP_USER, SMTP_PASS and SMTP_SERVICE
 * 11) Ensure that Mongo is running then seed the database with initial settings: node ./src/seed.js
 * 12) Run HabitRPG

Troubleshooting OS X
If you're having issues with OS X (the dreaded new worker : fork error), try clearing your trash, which may be difficult if node is holding on to a file--be sure to familiarize yourself with the "rm" command.

Set up MongoDB
In addition to the steps below, see also  Guidance for Blacksmiths: MongoDB
 * 1) Download the latest production release of MongoDB
 * 2) Extract the zip file to the desired application directory. Example: c:\apps\mongodb-win32-x86_64-2.4.6
 * 3) Rename the folder from mongodb-win32-x86_64-2.4.6 to mongodb
 * 4) Create a data\db directory under the application directory. Example: c:\apps\mongodb\data\db
 * 5) Start up MongoDB using this command: c:\apps\mongodb\bin\mongod.exe --dbpath c:\apps\mongodb\data

If MongoDB starts up successfully, you should see the following at the end of the logs: Sun Sep 01 18:10:21.233 [initandlisten] waiting for connections on port 27017 Sun Sep 01 18:10:21.233 [websvr] admin web console waiting for connections on port 28017

Install the Other Requirements

 * 1) Download and run the latest Node.js msi installation file - see also  Angular/Node/Jade Tips &amp; Best Practices
 * 2) Install and set up Git - see also Guidance for Blacksmiths: Git
 * 3) Fork the repository on your computer - refer to Fork &amp; Clone HabitRPG and/or GitHub's Fork A Repo
 * 4) Use checkout to move to the develop branch where all the development happens: git checkout -b develop origin/develop
 * 5) Install the npm packages: npm install You might receive the following error during the 'npm install' command: habitrpg@0.0.0-152 postinstall C:\Users\022498\Projects\habitrpg ./node_modules/bower/bin/bower install -f '.' is not recognized as an internal or external command, operable program or batch file. npm ERR! weird error 1 npm ERR! not ok code 0 Ignore this error and proceed with the following:
 * 6) Install grunt-cli and bower npm packages globally: npm install -g grunt-cli bower
 * 7) Install the bower packages: bower install -f
 * 8) Create a config file from the example one: cp config.json.example config.json
 * 9) Edit config.json with your values for ADMIN_EMAIL, SMTP_USER, SMTP_PASS and SMTP_SERVICE
 * 10) Ensure that Mongo is running then seed the database with initial settings: node ./src/seed.js
 * 11) Run HabitRPG

Run HabitRPG
HabitRPG uses Grunt as its build tool.


 * 1) From the command line of your habitrpg git directory, start the Mongoose database with: mongod
 * 2) On another Terminal tab, EITHER:
 * 3) Compile the Stylus files and start a web server with: grunt run:dev OR:
 * 4) Type: npm start which initiates 'grunt run:dev'
 * 5) Open a browser to http://localhost:3000 to test the application!

Note: 'grunt run:dev' uses Nodemon and grunt-contrib-watch to automatically restart the server and re-compile the files when a change is detected.

If you continue to have issues, further information about troubleshooting is available.

Updating
As other authors make changes to HabitRPG, your local copy will fall behind. To bring it up to speed, do the following: git pull upstream develop npm install # only do `npm update` if you want to update Habit's dependencies and you know what you are doing bower install -f # do `bower update` to update dependency versions if you know what you are doing

Other Resources
Contributing to HabitRPG has information about the technologies used, how the HabitRPG code is structured, and ideas for how you can help.

Guidance for Blacksmiths has tips for using Git, MongoDB, Angular/Node/Jade, and other information.

Technologies discussion

 * Angular, Express , Mongoose . Awesome, tried technologies. Read up on them.
 * Stylus, Jade - big debate.
 * Jade : We need a server-side templating language so we can inject variables (res.locals from Express). Jade is great because the "significant whitespace" paradigm protects you from HTML errors such as missing or mal-matched close tags, which has been a pretty common error from multiple contribs on Habit. However, it's not very HTML-y, and makes people mad. We'll revisit this conversation after the rewrite is done.
 * Stylus : We're either staying here or moving to LESS, but vanilla CSS isn't cutting it for our app.