Setting up Habitica Locally

The first step to contributing code to Habitica is setting up a local instance of Habitica to test changes before contributing them to the main repository. This page contains instructions for how to do this in all major operating systems. Read each section in order, ensuring that every instruction is followed before moving on to the next.

Important Notes
(On Windows, I have no idea, sorry. If someone has information about it, please add it here! LadyAlys (talk) 12:07, April 26, 2016 (UTC))
 * It is important that you also read Guidance for Blacksmiths.
 * As of March 2016, Habitica requires nodejs 4 with npm 2. You will experience errors if you use nodejs 5 and/or npm 3. Instructions for installing node and npm are provided below but please keep this version information in mind if you already have node and npm on your system!
 * On Unix, Linux, and Mac OS X, it is likely that you will need a swap file, otherwise you will have persistent errors. Refer to this github comment for details.
 * If you need help, ask in the Aspiring Coders guild or by logging an issue in GitHub. Please upload the full output of all installation steps that you have attempted so far to a site such as GitHub Gist and then paste the link to the output into the guild or the GitHub issue.

Install Git
Create a GitHub account if you don't already have one.

Install  on your machine (installation instructions available here).

On Windows, it is essential that Git is installed without modifying the Unix LF setting to CR/LF (select option: "Checkout as-is, commit Unix style line endings"). If you're unable to change that, refer to the "Per-repository settings" section in GitHub's Dealing with line endings article.

Fork and Clone Habitica (All Operating Systems)
Regardless of which operating system you're using, you need 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 GitHub's Fork A Repo article.


 * 1) Fork Habitica's repository by going to https://github.com/HabitRPG/habitrpg and clicking on the "Fork" button. This creates a copy of Habitica's repository in your own GitHub account.
 * 2) On your machine, open a command prompt or terminal window. Change to the directory that you want to Habitica's codebase to be copied under.
 * 3) Clone your copy of Habitica's repository with the command below (replace "YourUsername" with your GitHub username). This will copy Habitica's code onto your machine, placing the repository into a new "habitrpg" directory under your current directory.


 * 1) Change into the "habitrpg" directory that was created by the above step:

Remain in that directory for all future steps on this page.
 * 1) Configure Git to sync your fork with Habitica's repository.

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)
 * 1) Verify that everything is set up properly by typing  which should produce output the same as the following but with your GitHub username in place:

After you have cloned Habitica's repository, you will be in the  branch by default. This is the correct branch to be in when installing Habitica locally. You do not need to change to any other branches but if you do for any reason, you must switch back to the develop branch with  before proceeding further with the installation. You can check which branch you are one with  (the branch with a star next to it is the branch you are currently on).

Initial Configuration
Note for Windows: All  commands on this page should be replaced with


 * 1) Create the config.json configuration file from the example one:


 * 1) Normally you do not need to edit config.json, but if you are aware of any reason to, you can do it now. It can also be edited at any later time if needed.
 * 2) In contrast to previous instructions found here, there is no reason to change the values for ADMIN_EMAIL, SMTP_USER, SMTP_PASS and SMTP_SERVICE. They are used to configure the sending of emails and the email features will not work in development, even with those values supplied.

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

(Previously, versions greater than 4.x didn't work well with Vagrant, so we were recommending that you install version 4.3, however Alys believes that issue is now resolved and that the most recent version of VirtualBox is best. If that doesn't seem to be the case for you, please ask about it in the Aspiring Coders guild.)
 * 1) Install the latest version of the free virtual machine software VirtualBox.
 * 1) Install the latest version of Vagrant. The process below will automatically fetch a Vagrant box from vagrantcloud.com; if you receive errors such as "The box 'thepeopleseason/habitrpg' could not be found" then you are not using the latest version of Vagrant and will need to upgrade it.
 * 2) If your host machine is Windows, open a Command Prompt window with administrative rights. For other operating systems, open a terminal window.
 * 3) Copy the Vagrantfile from the example one:


 * 1) If desired, increase the amount of memory and number of CPUs allocated to the box by editing Vagrantfile 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).
 * 2) Boot the Vagrant box (the first time you do this it can take 30 to 60 minutes):


 * 1) *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 hardware virtualization is enabled.
 * 2) *If "vagrant up" finishes successfully, it will say:


 * 1) Login to the environment (a Ubuntu Linux virtual machine):


 * 1) *Before that command will work, your PATH variable must include the ssh program. This will already be correct for Unix, Linux, and Mac OS users. For Windows users, you most likely have ssh in the Git directory and if it's not already in your PATH, you can add it with:


 * 1) Install required node modules. This will take many minutes. Due to a bug you may have to run it twice.


 * 1) Follow the instructions in the Run Habitica section below.

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:

Note: 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.

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.

Install NodeJS and npm for Unix

 * 1) Check that inappropriate versions of NodeJS and npm are not installed:


 * 1) *If that shows that node/nodejs is not installed, proceed to the next step.
 * 2) *If it shows that you have a version of node/nodejs that is not version 4.x, uninstall it. On Ubuntu, the commands to uninstall it are:


 * 1) Install NodeJS version 4.x for your version of Unix (NodeJS downloads, NodeSource Node.js binary distributions).
 * 2) *For Ubuntu, whose software repositories may run a few months behind the latest revisions, install NodeJS from an updated repository:


 * 1) Check that you installed node successfully and that it is version 4.x:


 * 1) *If that command tells you that  is not installed, your executable is probably called  . Check its version, and if it is correct, link it to the name  :


 * 1) Installing NodeJS also installs npm. Check that that has been done and that the version is 2.x:


 * 1) *If you have npm version 3.x, uninstall it and ensure that version 2.x is installed. If you need help with that, ask in the Aspiring Coders guild.

Install Other Generic Requirements for Unix
If you are using Ubuntu 14.04, follow these steps to install and start MongoDB: 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 The Mongo repo doesn't currently have packages for Ubuntu 15.04 and later. This Ask Ubuntu discussion describes a workaround.
 * 1) Install MongoDB in the appropriate way for your version of Unix. Start the  server, if needed (it is likely that it will be started automatically as part of the installation process).


 * 1) Install some npm packages globally (on some systems you may need to add  in front of this command): npm install -g gulp grunt-cli bower

Install Habitica-Specific Requirements for Unix

 * 1) Install the Habitica-specific npm and bower packages: npm install
 * 2) *For OS X, if "npm install" gives a fatal error, install bower and npm separately: bower install; npm install
 * 3) *For any Unix OS, if "npm install" fails, try rerunning it again until it succeeds, clearing the npm cache first each time:


 * 1) *For OS X, if you see a "new worker : fork" error, empty your Trash. This might be difficult if node is holding on to a file, so use the "rm" command to delete any items remaining in Trash.
 * 2) Follow the instructions in the Run Habitica section below.

Set up MongoDB for Windows

 * 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 for Windows

 * 1) Close any applications or file explorer windows that might be reading your local copy of the repository. The installation steps might fail if any of the files are locked by any Windows processes. For antivirus software, make an exception in its settings so that it won't scan the repository until the install is complete. For reference, see from this GitHub comment to the end of the issue.
 * 2) Download and run the latest Node.js msi installation file
 * 3) Install some npm packages globally: npm install -g gulp grunt-cli bower
 * 4) Install the Habitica-specific npm packages:


 * 1) *You might receive the following error during the 'npm install' command but you can ignore it:


 * 1) Install the bower packages:

(In theory, that should not be necessary because it should be included in the "npm install" command above. If any Windows users have any feedback about that, please comment in the Aspiring Coders guild!)
 * 1) Follow the instructions in the Run Habitica section below.

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

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

Follow the instructions in the Run Habitica section below.

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.

It is recommended that you first read the instructions at the top of this page (everything up to the "Instructions by Operating System" section) and follow them where necessary because they have been modified since the Uberspace process was written.

After following the Uberspace guide, follow the instructions in the Run Habitica section below.

Run Habitica

 * 1) Ensure that the MongoDB database server is running. It should be if you have just completed the above steps, but if you are returning to your local install after a break, it might need to be restarted; refer to online MongoDB instructions for your operating system or ask in the Aspiring Coders guild if you need help.
 * 2) In a command prompt or terminal window, compile various files and start a web server with:


 * 1) *Ignore this warning message if you see it:


 * 1) Stylus_hang.png"npm start" can take several minutes. Wait until you see the following on the command line:


 * 1) *If after several minutes, "npm start" seems to have frozen before reaching that point (e.g., as shown in the screenshot), hit  and run   again.
 * 2) Open a browser to http://localhost:3000 to test the application.
 * 3) *Note that "3000" is the default port used by the installation scripts, however if you have changed it in the "config.json" file, then you must change it in the URL too.
 * 4) *For Vagrant installations, if port 3000 was already in use by any service on your machine, Vagrant will have automatically selected another port between 3000 and 3050, and will have listed that port in its output.
 * 5) If you get to the website's front page but the Play button does nothing, or if you get to the login screen but the login button does nothing, clear local storage for the "localhost" domain. You can do that by clicking the button at http://localhost:3000/static/clear-browser-data or by using your browser's JavaScript console (google for information about how to clear local storage in your preferred browser). Then reload the front page.
 * 6) Create one or more accounts for your testing. The database used by your local install is hosted on your machine; it is not the same database that is used by Habitica itself and so your normal Habitica account will not be available to you.

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 by rerunning "npm install" - if this is necessary, you should see errors about missing modules. Ask in the Aspiring Coders guild if you need help. Further instructions will be added to the wiki later.

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.
 * Post Installation troubleshooting might help if your local Habitica installation stops working after a while.