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. If you want to install Habitica directly onto Linux, MacOS, or Windows, there is a dedicated page of instructions for you:

• Setting up Habitica Locally on Linux
• Setting up Habitica Locally on MacOS
• Setting up Habitica Locally on Windows

If you would like to refer to the previous version of this page before those dedicated pages were created, it is available here.

If you want to install Habitica using Vagrant or Docker (regardless of which host operating system you are using), read on below. Dedicated pages will be created for them soon.

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

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:

• 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

You need to follow only one of those sub-sections - whichever one is appropriate for how you want to run Habitica locally.

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 command - 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 (npm WARN deprecated ...)
    • optional dependency failure warnings (npm WARN optional Skipping failed optional dependency...)
    • npm WARN notsup Not compatible with your operating system or architecture: fsevents@1.0.12
• 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 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 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 git on your machine (installation instructions available here).

Windows Line Endings

This section is only relevant if you are using Vagrant or Docker on a Windows PC.

*nix operating systems (Linux and Mac OS X) handle line endings differently than Windows. *nix systems use the line feed (LF) character \n, while Windows uses a combination of a carriage return and line feed, \r\n (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.

Configuring the line ending conversions

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 will be doing all your code editing in the Vagrant machine or Docker container, 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
git config --global core.autocrlf input

If you will be doing your code editing directly on your Windows host machine (i.e., you are using the Vagrant machine or Docker container to just run the Habitica server and tests), then select "Checkout Windows-style, commit Unix-style line endings", or configure it by running
git config --global core.autocrlf true

If you chose one setting now and later decide to change how you do your development work, you can use the appropriate git config --global core.autocrlf ... 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 core.autocrlf 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.
   git clone https://github.com/YourUsername/habitica.git
4. Change into the "habitica" directory that was created by the above step:
   cd habitica
   Remain in that directory for all future steps on this page, unless advised otherwise.
5. Configure Git to sync your fork with Habitica's repository.
   git remote add upstream https://github.com/HabitRPG/habitica.git
6. Verify that everything is set up properly by typing git remote -v which should produce output the same as the following but with your GitHub username in place:

  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)

After you have cloned Habitica's repository, you will be in the develop 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 git checkout develop before proceeding further with the installation. You can check which branch you are on with git branch (the branch with a star next to it is the branch you are currently on).

Initial Habitica Configuration

Note for Windows: All cp commands on this page should be replaced with copy

1. Create the config.json configuration file by copying (not renaming) the example one:
   cp config.json.example config.json
2. 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.
3. There is no reason to change the value for ADMIN_EMAIL. It is deprecated and will probably be removed soon.

Instructions by Operating System

This section contains the following sub-sections and you need to follow only one of them (ignore the others):

• Vagrant
• Docker

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.

1. Install the latest version of the free virtual machine software VirtualBox.
2. 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.
   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.
3. If your host machine is Windows, open a Command Prompt window with administrative rights. For other operating systems, open a terminal window.
4. Copy the Vagrantfile from the example one:
   cp Vagrantfile.example Vagrantfile
5. If desired, increase the amount of memory and number of CPUs allocated to the box by editing Vagrantfile and modifying the values for v.memory and v.cpus. When vagrant up 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 vagrant destroy 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 vagrant reload (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 v.memory 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.
6. Boot the Vagrant box (the first time you do this it can take 30 to 60 minutes):
   vagrant up

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.
   • If "vagrant up" finishes successfully, it will say:
     'vagrant up' is finished. Continue with the instructions at http://habitica.wikia.com/wiki/Setting_up_Habitica_Locally"
2. Login to the environment (a Ubuntu Linux virtual machine):
   vagrant ssh

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:
     set PATH=%PATH%;C:\Program Files (x86)\Git\bin
2. 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 vagrant@habitrpg:/vagrant$
3. Check that the correct versions of NodeJS and npm have been installed:
   node --version; npm --version
   Important: You must install exactly node 14 and npm 6. You will experience errors if you use any other versions, including later versions. 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.
   • If incorrect versions have been installed, please report it by logging an issue in GitHub 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.
4. Install required node modules (this will take many minutes):
   npm install

1. • If an error occurs, run npm install a second time.
   • On a Windows host, you may need to run this with elevated permissions, and tell npm to install without making symlinks, to avoid errors: sudo npm install --no-bin-links. You may also need to install bcrypt manually: sudo npm install bcrypt.
   • If you still see error messages during the second time, please log an issue in GitHub to report the problem. State that you ran it twice. We will give you advice about running each part of npm install 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).
2. Run these commands:
   • gulp build
3. 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 /home/vagrant/.bashrc to remove the line ('cd /vagrant').

Note: In creating the Vagrant environment, a configuration option automatically exports the DISPLAY environment variable to :99 in /home/vagrant/.bashrc. 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: You can opt to have the initial "vagrant up" command start the entire system (i.e., run npm start). 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 autostart_habitrpg. 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 little setup and ensuring a consistent environment for all developers. It also means that you do not need to clutter your host machine with dependencies.

Assistance with these Instructions

The instructions in this Docker section might be outdated or incorrect in parts. If you need help, post to the Aspiring Blacksmiths guild.

If you are familiar with Docker, your assistance in improving these instructions would be most welcome! Here are some points of confusion that contributors have identified:

• Not entirely clear the difference between the steps: "Use docker-compose to build and start...", "Bootstrap your local clone using...". Are they dependent of each other? Can one step be followed instead of the other? If one step is an optional step, a label that states "optional" may be very helpful. If one step must be followed after the conclusion of another step, then statements like "Go to ----" at the end of the step may be helpful.
• Running the command `docker-compose exec web sh` produced error `ERROR: No such service: web`. This has been reproduced by another member of our group who has successfully installed npm while I failed (not sure if that factor is connected to the issue but thought it may be useful to mention).

Initial Docker Setup

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 all the directions in this page before the "Instructions by Operating System" section.

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 docker-compose.yml file will build a habitica container using the Dockerfile build file and pull the latest mongo image:
docker-compose up -d This will start three containers in the background.

$ docker ps
 CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES
 cf95c4331acf        habitica_client     "npm run client:dev"     25 hours ago        Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1
 f9bda8e04e9e        habitica_server     "npm start"              25 hours ago        Up 6 seconds        0.0.0.0:3000->3000/tcp             habitica_server_1
 17edaab645a4        mongo               "docker-entrypoint.s…"   2 days ago          Up 7 seconds        0.0.0.0:27017->27017/tcp           habitica_mongo_1

Habitica is available on port 3000 and mongo is on port 27017. The version of Habitica running in habitica_client is branch:develop 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 docker-compose again to stop these containers:
   docker-compose stop
2. Then mount your local clone directory to the habitica_client container and bootstrap:
   docker run -t --volume `pwd`:/usr/src/habitrpg habitica_client npm install
3. 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.

Note: The above step will create another container in your machine.

$ docker ps
 CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES
 a687e85ac965        habitica_client     "npm run client:dev"     10 minutes ago      Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1
 cf95c4331acf        habitica_client     "npm run client:dev"     25 hours ago        Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1
 f9bda8e04e9e        habitica_server     "npm start"              25 hours ago        Up 6 seconds        0.0.0.0:3000->3000/tcp             habitica_server_1
 17edaab645a4        mongo               "docker-entrypoint.s…"   2 days ago          Up 7 seconds        0.0.0.0:27017->27017/tcp           habitica_mongo_1

This extra container will have random name like elastic_keller and can be removed with docker rm [container_name].

If you experience any errors when running npm commands, check that the correct versions of NodeJS and npm have been installed:
node --version; nodejs --version
Important: You must install exactly node 14 and npm 6. You will experience errors if you use any other versions, including later versions. 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.
If incorrect versions have been installed, please report it by logging an issue in GitHub 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.

It is important that version 3.6 of MongoDB is used,

Running tests in the docker containers

Once you've started the two docker containers with docker-compose, you can attach to the habitrpg_client container for test execution.

$ docker-compose exec client sh
# <--here's your bash

Now you are in the container, and you can execute test suites using the test commands given in Using Your Local Install to Modify Habitica's Website and API.

While creating unit tests, you may also want to run a docker container that only runs tests.

$ docker run --name habitica_test -it --volume `pwd`:/usr/src/habitrpg habitica_client gulp test:${your_test_category}:watch

The command above creates a container called habitica_test, which you can stop and start for running tests.

Use an existing mongodb instance instead of the mongo container

If you want to avoid the mongodb docker container and instead run Habitica against an existing mongodb instance, launch the habitica_web container with an override to the NODE_DB_URI environment variable:
docker run --env NODE_DB_URI=mongodb://your/database habitica_web, or
docker run --env NODE_DB_URI=mongodb://your_hostname/habitrpg habitica_web

It is important that version 3.6 of MongoDB is used.

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 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 config.json.example to config.json, as noted on the top of this page.
4. In one command prompt or terminal window, run the client build with npm run client:dev. This will rebuild as you save changes to client files, and inform you of any errors.
5. In a second command prompt or terminal, compile various files and start a web server with:
   npm start and review the output.
   • If you see an error like [nodemon] Internal watch failed: watch /any/path/to/a/file ENOSPC, edit the .nodemonignore file to add website/raw_sprites/** as the final line. You'll find that file in the top level habitica directory (i.e., in the same directory as the config.json file). On Linux, if that does not fix it, execute this command:
     echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
     After implementing either of those fixes, run npm start again.
   • 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 Done, without errors there can still be errors above it that need to be resolved. It is possible that the errors will stop if you hit Ctrl-C and run npm start again.
   • npm start has finished when you see a line similar to info: Connected with Mongoose with no errors reported after it.
6. Open a browser to http://localhost:8080 to test the application.
   • Note that another port, 3000 by default, is used by Express. That port can be configured using the PORT variable in config.json.
   • 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.
   • The output of npm start will confirm the port in use: info: Express server listening on port 3000. If you do not see that message, then npm start has not run correctly.
7. 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:8080/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.
8. 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.

Next Steps: Using Your Local Install

Now that you have a working local install of the Habitica website, you can learn how to contribute code in Using Your Local Install to Modify Habitica's Website and API.

Also see Guidance for Blacksmiths, which has information about the technologies used, how the Habitica code is structured, ideas for how you can help, and other information.