Setting up Habitica Locally

The first step to contributing code to Habitica is setting up a local instance of Habitica. 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 Habitica's Aspiring Coders guild or by logging an issue in GitHub.
 * Post Installation troubleshooting - if your local Habitica setup stopped working after awhile.

Fork & Clone Habitica (All Operating Systems)
Regardless of which operating system you're using, the first step is to acquire a copy of Habitica'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. It is essential that Git is installed on Windows platforms without modifying the Unix LF setting to CR/LF (select option: "Checkout as-is, commit Unix style line endings").

Next, you need to fork Habitica's repository. Go to https://github.com/HabitRPG/habitrpg. Click the "Fork" button.

Next, clone your copy of Habitica's repository. This will copy Habitica'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 Habitica's repository. cd habitrpg 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/ YourUsername/habitrpg.git (fetch) origin	 https://github.com/ YourUsername/habitrpg.git (push) upstream	 https://github.com/HabitRPG/habitrpg.git (fetch) upstream	 https://github.com/HabitRPG/habitrpg.git (push)

Vagrant
Note: as of March 2016, installing Habitica from scratch is preferred to using the packaged Vagrant box. Therefore, this setup is not recommended at this time. The reason for this is that the Vagrant packaged box lags behind the development in the main repository.

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 Habitica development and the various issues developers may encounter setting up Habitica 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(note that the latest VirtualBox version, 5.0, isn't playing nice with Vagrant, so this link will get you the latest working version, 4.3) 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:

 Change into the 'habitrpg' folder that was created when you cloned the repository, then 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 Note that the Unix commands above should be replaced with  on a Windows host installation. 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 the next step). Boot up the vagrant 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. Install required node modules (due to a bug you may have to run this twice). npm install Note: If using vagrant on windows run with the  option. npm install --no-bin-links  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 Habitica 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.)</li> </ol>

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

Note: In creating the vagrant environment, a configuration option automatically exports the DISPLAY environment variable to :99 in. This is needed in order to run the end-to-end (e2e) test suite. If you are not using bash you have to manually export the variable before running tests with: export DISPLAY=:99 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 'vagrant_scripts/vagrant.sh' 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.

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10 echo "deb http://repo.mongodb.org/apt/ubuntu "$(lsb_release -sc)"/mongodb-org/3.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.0.list sudo apt-get update sudo apt-get install -y mongodb-org apt-get update apt-get install python-software-properties apt-add-repository ppa:chris-lea/node.js apt-get update apt-get install nodejs
 * 1) Install and set up MongoDB - see also Guidance for Blacksmiths: MongoDB but in a nutshell, for Ubuntu 14.04:
 * 1) 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 :
 * 1) Install and set up Git - see also Using Habitica Git
 * 2) Fork the repository on your computer - refer to the Fork &amp; Clone section earlier on this page and/or GitHub's Fork A Repo
 * 3) 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
 * 4) Install some npm packages globally (on some systems you may need to add sudo in front of this command): npm install -g gulp grunt-cli bower
 * 5) Install the Habitica-specific npm and bower packages: npm install
 * 6) 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
 * 7) Create a config file from the example one: cp config.json.example config.json
 * 8) 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.
 * 9) 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).
 * 10) Run Habitica

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) Follow the instructions provided at the MongoDB website for installing and starting MongoDB. (Specifically, the instructions here: Install MongoDB on Windows at the section Set Up the MongoDB Environment.

If MongoDB starts 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 Using Habitica 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 gulp grunt-cli bower
 * 6) Install the Habitica-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 Habitica

Docker
Docker allows development in containers requiring very little setup and asserting that everyone uses a consistent environment. It also means that you do not need to muddy up your host version with dependencies. Before beginning, follow the instructions for installing docker and docker-compose: https://docs.docker.com/compose/install/.

Clone the application using the instructions above then use docker-compose to build and start both the mongo database and habitrpg application. docker-compose up -d This will start two containers in the background. docker ps CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                        NAMES 4c9bcb599e97   habitrpg_web   "npm start"              31 seconds ago   Up 29 seconds   0.0.0.0:3000->3000/tcp       habitrpg_web_1 80e79eae6ceb   mongo          "/entrypoint.sh mongo"   28 minutes ago   Up 28 minutes   127.0.0.1:27017->27017/tcp   habitrpg_mongo_1 Habitrpg is available on port 3000 and mongo is on port 27017. When done, use docker-compose again to stop these containers. docker-compose stop The application files are stored in an ephemeral container so changes can be easily lost. It is safer and more convenient to mount a local clone in the container.

Bootstrap your local clone using the tools already installed in the container. cp config.json.example config.json docker run -t --volume `pwd`:/habitrpg habitrpg_web npm install docker run -t --volume `pwd`:/habitrpg habitrpg_web bower install --allow-root Run the containers using the local clone. docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d Now changes made to the local clone will be served via the container.

To use the docker container directly against an existing mongodb instance, override NODE_DB_URI env variable. docker run --env NODE_DB_URI=mongodb://your/database habitrpg_web

Uberspace
A guide to installing Habitica on a Uberspace is available at https://gist.github.com/mamiu/cc792b805eec59b224c9

Please note that currently the main Habitica 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 it 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 Habitica
Habitica uses gulp as its build tool.


 * 1) If MongoDB is not already running, start it (for instructions, refer to the appropriate section above for your operating system).
 * 2) On another Terminal tab (or pane, if using tmux or screen), compile various files and start a web server with: npm start
 * 3) Open a browser to http://localhost:3000 to test the application!

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

Quick Server Restart
After you've started the server (i.e., run ), the end of the console's output should look something like this: Running "nodemon:dev" (nodemon) task [nodemon] v1.2.1 [nodemon] to restart at any time, enter `rs` [nodemon] watching: *.* [nodemon] starting `node ./website/src/server.js` info: Express server listening on port 3000 info: Connected with Mongoose The lines about  mean that after you make any change to the code you'd like to test, you can simply type: rs

Then hit [Enter] to restart the server. This is faster than exiting and running  again.

The Debug Menu
The following menu is in the footer of every page of your local installation, and can be used to quickly trigger certain actions, making testing your code faster and more efficient.



Updating
As other authors make changes to Habitica, your local copy will fall behind. To bring it up to speed, refer to the "Rebase Branch" section in Using Habitica Git.

If node modules or bower components have been updated in Habitica, 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.

Other Resources

 * Guidance for Blacksmiths has information about the technologies used, how the Habitica code is structured, ideas for how you can help, tips for using MongoDB and Angular/Node/Jade, and other information.
 * Installation troubleshooting has some advice about specific problems you might encounter while installing Habitica.
 * Post Installation troubleshooting - if your local Habitica setup stopped working after awhile.