Setting up Habitica Locally

The first step to contributing code to HabitRPG is setting up a local instance of HabitRPG. This way, a developer can test their changes before contributing them to the main repository. This page contains instructions for how to set up a local copy on all major operating systems.

It is important that you also read:
 * Guidance for Blacksmiths
 * Installation troubleshooting - especially if you have any problems! If you can't find solutions there, ask in HabitRPG's "Aspiring Coders" guild or by logging an issue in GitHub.
 * Post Installation troubleshooting - if your local HabitRPG setup stopped working after awhile.

Fork & Clone HabitRPG (All Operating Systems)
Regardless of which operating system you're using, the first step is to acquire a copy of HabitRPG's codebase. There are multiple methods of doing this; the following is the simplest method, and is based on this GitHub article. These instructions assume that you have installed  on your machine (installation instructions available here), and have set up a GitHub account.

First, fork HabitRPG's repository. You can do this by navigating to HabitRPG's repository, and clicking the "Fork" button in the upper right hand corner of the page (directly under your profile picture).

Next, clone your copy of HabitRPG's repository. This will copy HabitRPG's code onto your machine, placing the repository in your current directory. Replace "YourUsername" with your GitHub username. git clone https://github.com/ YourUsername/habitrpg.git Next, you need to configure Git to sync your fork with HabitRPG's repository. git remote add upstream https://github.com/HabitRPG/habitrpg.git Verify that everything is set up properly by typing " ". The output should look similar to the following: origin	https://github.com/hairlessbear/habitrpg.git (fetch) origin	https://github.com/hairlessbear/habitrpg.git (push) upstream	https://github.com/HabitRPG/habitrpg.git (fetch) upstream	https://github.com/HabitRPG/habitrpg.git (push)

Vagrant (Recommended Setup)
Vagrant is a system to create reproducible and portable development environments; it provides a single development environment with minimal dependencies on the developer's local platform. Vagrant is recommended because of the variety of systems used for HabitRPG development and the various issues developers may encounter setting up HabitRPG on them.

You can use Vagrant on a variety of systems including Windows, Mac OS X, and Linux. These instructions are known to work well on Unix systems (Linux and Mac OS X), but Windows users can sometimes run into issues. If you do not have the option of using a Unix environment instead and run into issues setting up, file a bug on Github. (Vagrant is supposed to install cleanly, ideally. If you encounter multiple errors, you can also try using the Node JS instructions instead.)

First, install the free virtual machine software VirtualBox, then go to the Vagrant downloads page and download and install the software appropriate for your system.

The process below uses a Vagrant box from vagrantcloud.com; the box will be automatically fetched. 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:  Create a config file from the example one: cp config.json.example config.json  Copy the Vagrantfile from the example one: cp Vagrantfile.example Vagrantfile If desired, you can increase the amount of memory and number of CPUs allocated to the box by editing your copy of the file and modifying the values for   and. This should be done before proceeding further (if you decide later that you want to do this, do  and then restart the vagrant setup from this step). Change directory into the 'habitrpg' folder that had been created when you cloned the repository (i.e., the directory that contains the  file) then boot up the box (the first time you do this it can take 30 to 60 minutes): vagrant up  Login to the environment: vagrant ssh You'll be logged into an Ubuntu Linux virtual machine. Start the system (this can take up to 5 minutes): npm start  Wait until you see the following on the command line: info: Express server listening on port 3000 info: Connected with Mongoose   Open a browser to http://localhost:3000 to test the application. (By default, port 3000 will be used to run the HabitRPG server, however if you already have port 3000 mapped to another service, vagrant will use another port between 3000 and 3050, in which case you must adjust the localhost URL.) 

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.

Note: In creating the vagrant environment, a configuration option automatically changes the working directory to /vagrant (the location of the HabitRPG source) on login. If you do not wish to login to vagrant with that default directory, edit  to remove the final line ('cd /vagrant').

Note: In order for Vagrant to start the virtual box, hardware virtualization must be enabled for the system. If "vagrant up" is able to download the virtual box but not able to start it, reboot your system and check the BIOS settings to ensure that virtualization is enabled.

Note for Windows users: For the 'vagrant ssh' command to work, your PATH variable should include the ssh program. Most likely you already have one in the Git directory. You can add it through the graphical menu or by setting PATH in the cmd.exe you have opened: set PATH=%PATH%;C:\Program Files (x86)\Git\bin

If you encounter any difficulties getting your Vagrant environment up and running which you are not able to resolve yourself, file a bug on Github and mention '@thepeopleseason' in the body of your bug report.

Automatic Startup
You can opt to have the initial 'vagrant up' command start the entire system (i.e., run ). If you choose to do so, edit the file 'Vagrantfile' in your HabitRPG directory, and remove the '#' in front of the line Once the system is up and running, you will need to open another shell to run 'vagrant ssh', and you won't be able to interactively reload the server. Because of these deficiencies, you should only autostart the server if you know what you're doing.
 * 1) autostart_habitrpg

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. Users on any operating system that supports Vagrant can instead use the Vagrant steps above if they prefer.


 * 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 the Fork & Clone section earlier on this page and/or GitHub's Fork A Repo
 * 5) Make sure you are on the develop branch before continuing with the installation; 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 some npm packages globally (on some systems you may need to add sudo in front of this command): npm install -g grunt-cli bower phantomjs
 * 7) Install the HabitRPG-specific 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) If you will be testing features that require sending emails, edit config.json with your values for ADMIN_EMAIL, SMTP_USER, SMTP_PASS and SMTP_SERVICE. Otherwise there is no need to edit them. They can be edited at any later time, if required.
 * 11) Ensure that  is running (this is the MongoDB database server and it needs to keep running for the entire time you are writing and testing changes).
 * 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.

You may encounter an error during "npm install" that looks similar to this: npm ERR! Error: EACCES, mkdir '/users/USER/.npm/...'

If you get this error, you can try the following commands:

sudo chown -R $USER:$GROUP ~/.npm npm cache clean

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) Make sure you are on the develop branch before continuing with the installation; 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
 * 5) Install some npm packages globally: npm install -g grunt-cli bower phantomjs
 * 6) Install the HabitRPG-specific 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:
 * 7) Install the bower packages: bower install -f
 * 8) Create a config file from the example one: cp config.json.example config.json
 * 9) If you will be testing features that require sending emails, edit config.json with your values for ADMIN_EMAIL, SMTP_USER, SMTP_PASS and SMTP_SERVICE. Otherwise there is no need to edit them. They can be edited at any later time, if required.
 * 10) Ensure that  is running (this is the MongoDB database server and it needs to keep running for the entire time you are writing and testing changes).
 * 11) Run HabitRPG

Docker
A Docker container for HabitRPG is available at https://registry.hub.docker.com/u/uvwxy/habitrpg/

Please note that currently the main HabitRPG developers don't have experience with this Docker container and so they might not be able to assist you if you have problems while using it. However they have no objection to the use of this tool and you are welcome to ask for advice in the Aspiring Coders guild or on GitHub as long as you keep this caveat in mind.

Uberspace
A guide to install HabitRPG on an Uberspace is available at https://gist.github.com/mamiu/cc792b805eec59b224c9

Please note that currently the main HabitRPG developers don't have experience with this Uberspace process and so they might not be able to assist you if you have problems while using it. However they have no objection to the use of this tool and you are welcome to ask for advice in the Aspiring Coders guild or on GitHub as long as you keep this caveat in mind.

Run HabitRPG
HabitRPG uses Grunt as its build tool.


 * 1) From the command line of your habitrpg git directory, start the MongoDB database server with: mongod
 * 2) On another Terminal tab (or pane, if using tmux or screen), 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 in Installation troubleshooting.

Updating
As other authors make changes to HabitRPG, your local copy will fall behind. To bring it up to speed, refer to the "Rebase Branch" section in Guidance for Blacksmiths.

If node modules or bower components have been updated in HabitRPG, you will need to update them in your local install - if this is necessary, you should see errors about missing modules. For instructions, see "Missing node modules and/or bower components" in Installation troubleshooting.

Useful Resources for Beginners
If you don't know what these technologies are, you might find these links useful to help you set up and run your local install:


 * AngularJS:
 * Shaping up with Angular.js - A video tutorial with exercises. You'll probably find that the videos alone are enough to help you understand HabitRPG's AngularJS code, although of course completing the exercises too would be more beneficial.
 * Learn Angular - Free interactive lessons.
 * git:
 * Pro Git - An excellent resource. You will be much more comfortable with git if you take the time to read this.
 * git-it - scroll down to see more info. This is part of the nodeschool curriculum and is a fun and interactive way to learn git and github.
 * grunt: Grunt for People Who Think Things Like Grunt are Weird and Hard - Simple. Explains the basics. Probably enough for you to understand what's happening when you run grunt for HabitRPG development.
 * node.js:
 * How do I get started with Node.js
 * nodeschool - included in the SO article linked above, but a particularly awesome entry level interactive node curriculum

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.
 * Installation troubleshooting has some advice about specific problems you might encounter while installing HabitRPG.

Technologies Used

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

Versions Installed on Production HabitRPG Website
The version numbers listed here are the last known versions. It is possible that HabitRPG software has been updated since this was written.


 * MongoDB version 2.6 (as of October 2014)