Setting up Habitica Locally

The first step to contributing code to Habitica's habitica.com website is setting up a local instance of the website to test your changes. 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. It is important to also read Guidance for Blacksmiths. This page is not relevant for contributing to development for the mobile apps.

If you are upgrading a local install that was made before October 2016, it is recommended that you delete your local install and go through the full installation process described on this page.

Choose Your Platform
Most of the sections on this page must be followed regardless of which operating system you are using. However, when you come to the "Instructions by Operating System" section, you'll find it contains these sub-sections:

You need to follow only one of those sub-sections - whichever one is appropriate for how you want to run Habitica locally. You do not need to install the Vagrant, Docker, or Uberspace programs if you are not using those methods.
 * Windows - for installing Habitica directly onto a Windows PC
 * Mac OS / Linux / Unix - for installing Habitica directly onto a Mac or *nix computer (recommended if your PC runs one of those platforms)
 * Vagrant - for installing Habitica on a Ubuntu virtual machine using Vagrant, which can be run on Windows, Mac OS, and *nix (recommended for Windows if you have trouble creating an install directly on Windows, but not recommended otherwise)
 * Docker - for running Habitica in a Docker container
 * Uberspace - for running Habitica using Uberspace

Prepare for Troubleshooting
A local install does not always go smoothly but we will be happy to help you! Habitica uses a lot of software and we understand that it can be complicated to install it all until you are used to it. Please follow all the steps in this section before you experience errors so that, if necessary, you can ask for help easily and we can assess your problem rapidly.

As you are installing Habitica:


 * Record every command that you type and the full output of every commmand - save all the commands and outputs into text file(s) in case we need to see them later.
 * Carefully read all output messages to look for errors.
 * If you see an error, do not proceed further until the error has been resolved because later steps are likely to not work correctly.
 * However, you can ignore:
 * deprecation warnings
 * optional dependency failure warnings
 * If you need to deviate from any instructions anywhere on this page, record what you have done that is different and why. If you later need assistance, it is vital that the people helping you know about those differences, otherwise time can be spent on advice that isn't relevant to you.
 * If you need to deviate from any instructions anywhere on this page, record what you have done that is different and why. If you later need assistance, it is vital that the people helping you know about those differences, otherwise time can be spent on advice that isn't relevant to you.

If you need help with fixing any errors, upload all of the information you have gathered so far onto a site such as GitHub Gist, then either post in the Aspiring Blacksmiths (Habitica Coders) guild or log an issue in GitHub and tell us all of this:
 * which operating system your PC/laptop is running
 * which of the following methods you are using:
 * installing Habitica directly onto your PC/laptop
 * installing Habitica using the Vagrant or Docker or Uberspace instructions on this page
 * installing Habitica onto some other virtual machine - include which operating system it is running
 * any deviations you needed to make from the standard instructions
 * any other information the instructions on this page asked you to record
 * links to your uploaded file(s)
 * what problem you're experiencing

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

Install  on your machine (installation instructions available here).

Windows Line Endings
This section is only relevant if you are using a Windows PC (either with or without Vagrant).

* nix operating systems (Linux and Mac OS X) handle line endings differently than Windows. *nix systems use the line feed (LF) character, while Windows uses a combination of a carriage return and line feed,   (CRLF). Since Habitica developers use a variety of operating systems, to allow for maximum compatibility, Git on Windows must be set up to ensure that only LF line endings are committed to the repo.

How you set this up depends on whether you will be doing all your Habitica development work directly in Windows or you will be installing a Unix Vagrant virtual machine on your Windows PC and using the Vagrant machine for all development. The appropriate setting can be chosen when installing Git (see the screenshot but read on before you chose an option) or afterwards using a simple command-line tool.

If you are intending to install Vagrant as described later in this page and will be doing all your Habitica development in the Vagrant machine, then when presented with the "Configuring the line ending conversions" window, select "Checkout as-is, commit Unix-style line endings". Alternatively, configure that setting from the command line by running

If you will not be using a virtual machine and instead will be doing all your development work directly in Windows, then select "Checkout Windows-style, commit Unix-style line endings", or configure it by running

If you chose one setting now and later decide to change how you do your development work, you can use the appropriate  command to change the setting.

For further information on line endings and whitespace in Git, see the "Formatting and Whitespace" section in the Pro Git book.

If you don't want to set the  setting globally, see Dealing with line endings > Per-repository settings to learn how to set it for individual repositories. This will only be relevant to you if you are already using Git for other projects or will be using it for others in future.

Fork and Clone Habitica
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/habitica 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 "habitica" directory under your current directory.


 * 1) Change into the "habitica" 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/habitica.git (fetch) origin  https://github.com/ YourUsername/habitica.git (push) upstream https://github.com/HabitRPG/habitica.git (fetch) upstream https://github.com/HabitRPG/habitica.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 on with  (the branch with a star next to it is the branch you are currently on).

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


 * 1) Create the config.json configuration file by copying (not renaming) 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) 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.

Node and npm Versions
The instructions below include steps for installing Node and npm. When you reach those steps, be aware that the correct versions to use are Node 6 and npm 4. You will experience errors if you use any other versions. The instructions will tell you how to find which versions you have installed.

The version numbers are not necessarily listed below to avoid the instructions becoming inaccurate if we forget to update one section when the version numbers change. Please refer to this section whenever you need to know the correct versions to use.

If you need to use different versions on your development machine for work not related to Habitica, you can use nvm to manage the versions.

Instructions by Operating System
This section contains the following sub-sections and you need to follow only one of them (ignore the others):
 * Windows
 * Mac OS or Linux or Unix
 * Vagrant
 * Docker
 * Uberspace

Windows
If it gives you an error that the directory already exists, ignore the error and proceed with the next step
 * 1) Install the Visual C++ 2015 build tools. This step might not be necessary but recent contributors using Windows installs have indicated that it might be needed for some of Habitica's dependencies to be installed (e.g., bcrypt). If you have feedback about this, please post to the Aspiring Blacksmith's guild.
 * 2) Follow the MongoDB's official instructions to install MongoDB Community Edition on Windows.
 * 3) 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.
 * 4) Download and run the latest Node.js msi installation file. Refer to the Node and npm Versions section above for the correct versions to install.
 * 5) *To check which version you have installed, enter the following commands in a command window: node -v npm -v
 * 6) *If you do not have the correct versions and aren't sure how to fix that, ask for help in the Aspiring Blacksmith's guild.
 * 7) Launch a command window as Administrator and in that window:
 * 8) *Install some npm packages globally: npm install -g gulp grunt-cli bower mocha
 * 9) *Install some dependencies necessary for the bcrypt package: npm install -g node-gyp npm install --global --production windows-build-tools If this doesn't work you may have to install some extra dependencies listed here: https://github.com/kelektiv/node.bcrypt.js#dependencies.
 * 10) Close the command window and open a new one without using Administrator permissions so that all further instructions are run as a non-Administrator user.
 * 11) Create a directory by executing
 * 1) Install the Habitica-specific npm packages:


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


 * 1) Run these three commands:
 * 2) Sometimes it is necessary to run  and the three commands listed after it two or three times before they are successful. If any subsequent steps on this page show you errors about missing modules or files, run those four commands again.
 * 3) If you receive any error messages not described above, please report the problem in the Aspiring Blacksmiths (Habitica Coders) guild.
 * 4) Follow the instructions in the Run Habitica section below.
 * 1) Sometimes it is necessary to run  and the three commands listed after it two or three times before they are successful. If any subsequent steps on this page show you errors about missing modules or files, run those four commands again.
 * 2) If you receive any error messages not described above, please report the problem in the Aspiring Blacksmiths (Habitica Coders) guild.
 * 3) Follow the instructions in the Run Habitica section below.

Set Up a Swap File on Mac OS / Linux / Unix
It is likely that you will need a swap file of at least 4 GB, otherwise you will have persistent errors when running the "npm install" and "npm start" commands (for examples of errors, see this GitHub issue). Your computer might already have a swap file. Find appropriate instructions on the internet for viewing or creating a swap file for your platform.

If you have a swap file but still cannot run the "npm install" and "npm start" commands successfully, try increasing the size of the swap file.

Record the size of your swap file now. If you later need to ask for help, include it in the troubleshooting information if you give us.

For the remainder of these instructions, you should not be logged in as the root user. Log in with the user account that you will be using when you are developing for Habitica. The instructions will specify  when root permissions are needed and using root permissions at other times will cause problems.

Install NodeJS and npm for Mac OS / Linux / Unix

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


 * 1) *Refer to the Node and npm Versions section above for the versions that are needed.
 * 2) *If that command shows that node/nodejs is not installed, proceed to the next step.
 * 3) *If it shows that you have a version of node/nodejs that is less than the required version, uninstall it. On Ubuntu, the commands to uninstall it are:


 * 1) Install the correct version of NodeJS for your flavour 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. For example, if Node 6 needs to be installed:

Refer to the Node and npm Versions section above for the correct version.
 * 1) Check that you installed node successfully and that it is the correct version or better:


 * 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 correct:


 * 1) *If you have any other version of npm, upgrade it to the correct version. For example, if npm 4 needs to be installed:

Refer to the Node and npm Versions section above for the correct version.

Install Other Generic Requirements for Mac OS / Linux / Unix

 * 1) Install MongoDB in the appropriate way for your version of Unix. It is recommended that, where possible, you follow MongoDB's official instructions which can be found at Install MongoDB Community Edition on Linux and Install MongoDB Community Edition on OS X. The instructions for Linux are broken down by distribution, so follow the appropriate link. For Ubuntu versions greater than 14.10, if the instructions have not yet been updated for your version, try one of these unofficial workarounds: workaround 1, workaround 2), but please assess them carefully to determine suitability for your system.
 * 2) Start the MongoDB server if it was not started during the installation process (the instructions above should tell you how).
 * 3) Install some npm packages globally: sudo npm install -g gulp grunt-cli bower mocha

Install Habitica-Specific Requirements for Mac OS / Linux / 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.

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.

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 Blacksmiths (Habitica Coders) guild.) ''Note: If you receive an error saying "The requested address is not valid in its context. - connect(2) for "0.0.0.0" port 3000 (Errno::EADDRNOTAVAIL)", this could be due to a bug in Vagrant v1.9.3, which will be fixed on the next release. The temporary workaround is to downgrade to Vagrant v1.9.2.''
 * 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.
 * 1) If your host machine is Windows, open a Command Prompt window with administrative rights. For other operating systems, open a terminal window.
 * 2) 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  . When   is run the first time, scripts are executed to provision the virtual machine with software packages required for habitica. If any of these fail due to memory or cpu issues, run   and then restart the Vagrant setup from the next step. However memory and cpus can be changed after the first vagrant up has been successful by simply modifying the values and running   (This might be helpful to allocate more memory and cpu for the initial setup and then reducing it for daily use). You may want to increase   to avoid swap files, or decrease it if your computer does not have enough memory to allocate to the box. However, be aware that not allocating enough memory may lead to errors; see Important Notes above.
 * 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) Check that the ssh command was successful and that you are now in the vagrant machine. If you are not, do not proceed further with these instructions until you have been able to ssh to the vagrant machine. If ssh was successful, the vagrant machine's prompt will be
 * 2) Check that the correct versions of NodeJS and npm have been installed:


 * 1) *Refer to the Node and npm Versions section above for the versions that are needed.
 * 2) *If incorrect versions have been installed, please report it in the Aspiring Blacksmiths guild so that we can fix the vagrant install script. If you are not sure how to install the correct versions, you can ask for help there.
 * 3) Install required node modules (this will take many minutes):


 * 1) *If an error occurs, run  a second time.
 * 2) *On a Windows host, you may need to run this with elevated permissions, and tell npm to install without making symlinks, to avoid errors: . You may also need to install bcrypt manually:.
 * 3) *If you still see error messages during the second time, please post in the Aspiring Blacksmiths (Habitica Coders) guild to report the problem. State that you ran it twice. We will give you advice about running each part of  individually (if you feel comfortable doing that yourself, you can, but please do post to the guild as well to help us track the occurrence of this problem).
 * 4) Run these commands:
 * 5) Follow the instructions in the Run Habitica section below.
 * 1) Follow the instructions in the Run Habitica section below.
 * 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 habitica 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.

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

Verify your installation by clicking the Docker Quickstart Terminal icon on your Desktop (Windows) or Launchpad (Mac OS X). Follow the directions above to install Git, fork a copy of the habitica repository, and clone it to your local machine. In the Docker Quickstart Terminal, cd to your local habitica folder.

Use docker-compose to build and start both the mongo database and habitica application
The  file will build a habitica container using the   build file and pull the latest mongo image:

This will start two containers in the background. $ docker ps CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                        NAMES 4c9bcb599e97   habitica_web   "npm start"              31 seconds ago   Up 29 seconds   0.0.0.0:3000->3000/tcp       habitica_web_1 80e79eae6ceb   mongo          "/entrypoint.sh mongo"   28 minutes ago   Up 28 minutes   127.0.0.1:27017->27017/tcp   habitica_mongo_1

Habitica is available on port 3000 and mongo is on port 27017. The version of Habitica running in  is   of the Habitica repository.

Note: The application files are stored in an ephemeral container so changes can be easily lost. It is safer and more convenient to mount your local clone of the Habitica repository in the container.

Bootstrap your local clone using the tools already installed in the container.

 * 1) Use  again to stop these containers:


 * 1) Then mount your local clone directory to the  container and bootstrap:


 * 1) Run the containers using the local clone:

Now changes made to the local clone will be served via the container.

Note: The above step will create two containers in your machine. $ docker ps -a CONTAINER ID       IMAGE               COMMAND                  CREATED             STATUS                      PORTS               NAMES 19c16247ff69       habitrpg_web        "bower install --a..." 4 minutes ago      Exited (0) 3 minutes ago                        infallible_darwin 515e370cc936       habitrpg_web        "npm install"            30 minutes ago      Exited (0) 26 minutes ago                       elastic_keller 81e8c7aa0181       habitrpg_web        "npm start"              44 minutes ago      Exited (0) 31 minutes ago                       habitrpg_web_1 6bd0dac0ba4c       mongo               "/entrypoint.sh mo..." 4 weeks ago        Exited (0) 31 minutes ago                       habitrpg_mongo_1 These two containers will have random names like elastic_keller and can be removed with docker rm [container_name].

If you experience any errors when running  commmands, check that the correct versions of NodeJS and npm have been installed:

Refer to the Node and npm Versions section above for the versions that are needed. If incorrect versions have been installed, please report it in the Aspiring Blacksmiths guild so that we can fix the docker configuration. If you are not sure how to install the correct versions, you can ask for help there.

Running tests in the docker
Once you've started the two docker containers with docker-compose, you can attach to the hatibrpg_web container for test execution. $ docker-compose exec web sh Now you are in the container, and you can execute test suites with $ npm test While creating unit test, you may also want to run a docker container that only run tests. $ docker run --name habitrpg_test -it --volume ~/habitrpg:/habitrpg habitrpg_web gulp test:${your_test_category}:watch The command above creates a container called habitrpg_test, which you can stop and start for running tests.
 * 1)  <--here's your bash

Use an existing mongodb instance instead of the mongo container
To avoid the mongodb docker container and instead run Habitica against an existing mongodb instance, launch the  container with an override to the NODE_DB_URI environment variable: , or

Follow the instructions in the Run Habitica section below.

Uberspace
"The configuration files for Uberspace have not been updated for APIv3. Please do not use till further notice."

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 Blacksmiths (Habitica 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
and review the output.
 * 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 Blacksmiths (Habitica Coders) guild if you need help.
 * 2) Ensure that the time set on your computer or virtual machine is accurate to the nearest second, otherwise you will see "RequestTimeTooSkewed" errors.
 * 3) Ensure you have copied  to , as noted on the top of this page.
 * 4) In a command prompt or terminal window, compile various files and start a web server with:
 * 1) *Ignore these errors and warning messages:
 * 2) ** (this will be followed by several lines starting with   and then a   message, ending with a   line).
 * 3) *Stylus_hang.png If you see any other errors or warning messages, before going any further, resolve them yourself or report them using the guidelines in the Prepare for Troubleshooting section above. Note that even if the output ends with  there can still be errors above it that need to be resolved, as in this screenshot. It is possible that the errors will stop if you hit   and run   again.
 * 4) * has finished when you see a line similar to
 * 5) Open a browser to http://localhost:3000 to test the application.
 * 6) *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.
 * 7) *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 own output.
 * 8) *The output of  will confirm the port in use:  . If you do not see that message, then   has not run correctly.
 * 9) 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.
 * 10) 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.
 * 1) 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.
 * 2) 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.

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.

Installer Habitica localement