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 that in Windows.
If you are using a different operating system (or a virtual machine hosted on Windows but containing a different operating system), or if you want to contribute to development for the mobile apps, refer to the links in Setting up Habitica Locally.
Read each section on this page in order, ensuring that every instruction is followed before moving on to the next. If you experience errors, always stop and solve them before moving on to the next step.
It is important to also read Guidance for Blacksmiths for background information about coding for Habitica.
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 a text file, or files, 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.
Screenshots can be an easy way to record errors but aren't as good for analyzing them, so if at all possible please provide the full error messages as text. This lets admins paste relevant parts into GitHub issues or into Google searches.
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 and post all of the information you have gathered to the GitHub issues tracker and tell us the following:
what version of Windows you are using
any deviations you needed to make from the standard instructions
any other information the instructions on this page asked you to record
link(s) to your uploaded file(s)
what problem you're experiencing
A key step to troubleshooting is being able to recreate the problem. For someone else to be able to help troubleshoot, unless they are already familiar with the problem, they will usually need to be able to replicate the situation on another system. Thus, any information that could help someone else duplicate the scenario is valuable. You should also be able to duplicate the problem yourself. Sometimes starting from the beginning can solve the problem or help identify a possible cause of the problem.
Depending on how you installed Git, you may see a "Configuring the line ending conversions" window, similar to the screenshot shown here. It is important to select "Checkout as-is, commit Unix-style line endings".
Alternatively, after you have finished installing Git, you can configure that setting from the command line by running the git config command below. If you see an error about the git program not being found, move on to the "Putting Git in your PATH Variable" section below and then return here to run this comamnd. git config --global core.autocrlf input
Configuring line endings is necessary because Windows handles line endings differently than other operating systems. It uses a combination of a carriage return and line feed, \r\n (CRLF), while Unix/Linux/MacOS systems use only the line feed (LF) character \n. To force Windows to be compatible, you must set up Git to ensure that only LF line endings are committed to Habitica's GitHub repository.
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. Despite what that page says, you should not commit the .gitattributes file as we do not need it in Habitica's repo for all developers.
Putting Git in your PATH Variable[]
The folder in which the Git program was installed must be added to your PATH environment variable. Depending on how you installed Git, that may have been done automatically or the Git installer may have given you an option to do it. If neither of those happened, you will need to do it manually after installation using the steps below.
To test whether Git is in your path, open a Windows command prompt and type git --help then press Enter. If you see a list of available Git commands then Git is already in the PATH variable and you do not need to add it manually. If you see an error message or no output from that command, follow the steps below.
Find the folder where the Git executable file was placed during installation.
The drop-down arrow on the right can show you the Path.
If you are unsure where Git is located, the default installation often adds it to the Start Menu. Find it there, right click on it, and select "Open file location."
If doing so results in shortcuts to Git rather than the actual file location, select a shortcut, right click, and select "Open file location."
Search the internet to find reliable documentation about how to modify the PATH variable in your version of Windows (sample steps are given below for Windows 10).
Add the folder containing the Git program to your PATH variable.
Check that Git is now in your path using the test described above. If the git --help command still does not work, you may not have added the correct folder.
Setting the PATH on Windows 10[]
Go to the Control Panel (aka Windows Settings), type "environment variables" into the search field.
Select "Edit the System Environment Variables", and then click the "Environment Variables" button at the bottom of the "System Properties" dialog box.
Select Path, click Edit, and then add the path for Git to a new line. The default installation path is likely to be C:\Program Files\Git\bin or %USERPROFILE%\AppData\Local\Programs\Git\bin (for example, Michael Antonacci\AppData\Local\Programs\Git\bin) or C:\Users\... but confirm that on your own PC using the instructions above.
Click OK to save the path addition.
Test that the path was modified correctly as described above.
Install Build Tools[]
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.'
If you set up Habitica on Windows without installing the build tools and you find that your local install runs without errors, please tell us in the guild.
Install MongoDB[]
As of July 15, 2020, it is not necessary to manually install MongoDB. A MongoDB instance specifically for Habitica will be installed automatically as you follow the steps below. It is also not necessary to manually start Habitica's MongoDB server using MongoDB's standard server start command.
(Note that if you are running a MongoDB server for projects other than Habitica, it will conflict with Habitica's own MongoDB instance and so it will need to be stopped while your Habitica local install is running. More details about this are given below at the point where it will be necessary to stop it.)
Install Node and NPM[]
This section takes you through the process of installing node and npm.
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.
Note that the sample command below is for reference only and might not contain the correct version of npm so be sure to adjust the command as needed before you run it. The versions that must be used are exactly node 14 and npm 6
Launch a command window as Administrator and in that window:
Check that you installed node successfully and that it is the correct version (if it is not, redo the node installation using the correct download): node -v
Installing NodeJS also installs npm. Check that that has been done and that the version is correct: npm -v
If the version of npm is wrong, install the correct version. For example, if npm 6 needed to be installed: npm install -g npm@6
Note:
You may need to add C:\Program Files\nodejs;C:\Program Files\nodejs\node_modules\npm\bin to your PATH variable for node to work from the command-line.
Install Other Generic Requirements[]
Launch a command window as Administrator.
Execute this command: npm install -g mocha
Note: If you look at the Habitica repo's README file, you'll see it links to various services such as Greenkeeper. You do not need to install them on your local install.
Install some dependencies necessary for the bcrypt package: npm install -g node-gyp npm install -g --production windows-build-tools
If you later experience errors with bcrypt, you might need to install some extra dependencies listed here: https://github.com/kelektiv/node.bcrypt.js#dependencies . If you have any feedback about that, or experience problems with it, please post to the Aspiring Blacksmiths guild so that we can improve this documentation.
Note: After finishing the above steps, it is important that from this point onwards you are logged in to your computer using the same user account that you will use when you will be developing code for Habitica. Do not log in as Administrator. When elevated permissions are needed, this page will tell you to use the Administrator account. Using elevated permissions at other times will cause problems.
Close any command windows or terminal windows that you have open from previous steps. When you need a command/terminal window again, open a new one so that your shell environment is aware of the software you have installed so far.
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.
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.
If you had previously forked the repository, make sure your fork is up to date.
On your machine, open a command prompt or terminal window. Change to the directory that you want Habitica's codebase to be copied under.
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
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.
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:
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).
After you have followed all the steps above, you will be in Habitica's top-level directory. You must remain in that directory for all future steps on this page, unless advised otherwise. All commands below are written on the assumption that you are in that directory. If you change out of that directory for any reason, change back into it before continuing with the instructions on this page. If you want to check whether you are in the correct directory, look for a file called config.json.example - if you see that in your current directory, then you are in the right one.
Initial Habitica Configuration[]
Create your own copy of the config.json configuration file by copying (not renaming) the example file: copy config.json.example config.json
If desired, edit config.json:
Normally you do not need to do this, but if you are aware of any reason to, you can do it now. You can also edit it at any later time if needed.
One possible reason for editing config.json is to change the port that Habitica's Express server uses. By default, it uses port 3000 and there's no reason to change that unless you know that you are running other software on your machine that uses the same port. If you are, find the BASE_URL and PORT lines in config.json and change the port to a suitable number. Use the same number for both.
There is no reason to change the value for ADMIN_EMAIL. It is deprecated and may be removed in the future.
Do not edit config.json.example.
Create a directory by executing mkdir website\build If it gives you an error that the directory already exists, ignore the error and proceed with the next step
Close any applications or file explorer windows that might be reading your local copy of the repository. The installation steps below 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.
Install Habitica-Specific Requirements[]
Install the Habitica-specific npm packages: npm install
If that command shows errors, try rerunning it two or three times in case the failures are from timeouts while retrieving packages from the internet.
If you still see any errors or if any subsequent steps on this page show errors about missing modules or files, seek help as described above in the "Prepare for Troubleshooting" section.
Start the Habitica Web Server[]
If you are running a MongoDB server for a project other than Habitica, it will conflict with Habitica's own MongoDB instance. Stop that MongoDB server now using MongoDB's standard server stop command for your system. (You can safely restart it later after you have finished running the Habitica's servers.)
Ensure that the time set on your computer or virtual machine is accurate to the nearest second, otherwise you will see "RequestTimeTooSkewed" errors.
In one command prompt or terminal:
Start Habitica's own MongoDB instance with npm run mongo:dev
Wait until you see Started replica set on "mongodb://localhost:27017?replicaSet=rs" before moving on to the next step. (The first time you run this, it will download and install MongoDB within Habitica's directory so this will take several minutes.)
Do not attempt to use this terminal for anything else because the Mongo command needs to remain running there.
In a second command prompt or terminal window, start the Habitica web server with: npm start
In a third command prompt or terminal window, build the website client with npm run client:dev. This will rebuild itself automatically as you save changes to client files and will inform you of any errors.
Review the output of those three commands as described in the next section. If you have already noticed error messages, that section will help.
Below is an approach to run three commands programmatically.
Copy below bash script
Change pathToHabiticaRepo to where you copied the habitica repository
Save it as FILENAME.sh (Feel free to change FILENAME to your liking)
Run sh FILENAME.sh
Watch three terminals open and each runs separate commandsomatically
#!/usr/bin/env zsh
pathToHabiticaRepo="/Users/<YOUR_MAC_NAME>/Documents/habitica"
osascript - "$pathToHabiticaRepo" <<EOF
on run argv -- argv is a list of strings
tell application "Terminal"
do script ("cd " & quoted form of item 1 of argv & "&& npm run mongo:dev")
end tell
end run
EOF
osascript - "$pathToHabiticaRepo" <<EOF
on run argv -- argv is a list of strings
tell application "Terminal"
do script ("cd " & quoted form of item 1 of argv & "&& npm start")
end tell
end run
EOF
osascript - "$pathToHabiticaRepo" <<EOF
on run argv -- argv is a list of strings
tell application "Terminal"
do script ("cd " & quoted form of item 1 of argv & "&& npm run client:dev")
end tell
end run
EOF
Review the Server Output[]
The output from the npm run mongo:dev command should look something like the example below. You may see slight differences (e.g., different version numbers).
Skipping purge
Running '/home/alys/code/habitica/node_modules/run-rs/4.2.8/mongod' [ 27017 ]
Restarting replica set...
Started replica set on "mongodb://localhost:27017?replicaSet=rs"
The output from starting the server (from the npm start command) should look something like the example below. You are likely to see slight differences in your system (e.g., different dates, times, and version numbers). The text in italics describes the type of information you might see and is not verbatim.
[18:39:02] Using gulpfile ~/habitica/gulpfile.js
[18:39:02] Starting 'nodemon'...
[18:39:02] Finished 'nodemon' after 25 ms
[18:39:02] [nodemon] 1.19.4
[18:39:02] [nodemon] to restart at any time, enter `rs`
[18:39:02] [nodemon] watching dir(s): [directory path(s) here]
[18:39:02] [nodemon] watching extensions: js,mjs,json
[18:39:02] [nodemon] starting `node ./website/server/index.js`
(node:3348) [ "DeprecationWarnings" might be here and/or below; they do not indicate an error ]
2019-10-20T08:39:08.767Z - info: Express server listening on port 3000
2019-10-20T08:39:08.960Z - info: Connected with Mongoose.
The output from building the website client (from the npm run client:dev command) appears in two stages, first some initial text while the client is being built (which might then be cleared from the screen) and then output that shows the client is ready.
The first stage should look something like the example below, with the final line changing rapidly. The text in italics describes the type of information you might see and is not verbatim.
> habitica@4.116.8 client:dev /home/username/habitica
> cd website/client && npm run serve
Note that the development build is not optimized.
To create a production build, run npm run build. [This is just informational and not an instruction for you to follow.]
If you see any output significantly different than those examples, in particular errors or notable warning messages, before going any further, resolve them yourself or report them using the guidelines in the "Prepare for Troubleshooting" section at the top of this page. Here are some examples of errors with suggested fixes:
any error
First check that you are using the correct versions of node and npm, as described in Install Node and NPM above. This is especially important if you are using nvm to swap between versions as it might have swapped them without you realising.
ECONNREFUSED and/or Proxy error: Could not proxy request /api/v..... from localhost:8080 to http://localhost:3000
Check that your local database server is running using the instructions linked to from the Install MongoDB section above.
npm ERR! code ELIFECYCLE
If you are using Linux or Docker, this error is likely to be because nodemon requires more file watchers than inotify provides. Increase the number of file watchers. On Ubuntu and similar Linux distributions, you can do that using this command: echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/50-max-user-watches.conf && sudo sysctl --system For other distributions, refer to your distribution's documentation. An example of this error is shown in this issue.
If the outputs from npm run mongo:dev and npm start and npm run client:dev look good, proceed to the next section to test the website. If you're not completely sure if they are good or not, proceed anyway but if the website fails it's likely that you'll need to resolve problems shown in the outputs.
Test the Website in your Browser[]
Open a browser to http://localhost:8080 to test the application. The website should look the same as https://habitica.com and work identically except that on the Tasks page in the bottom left-hand corner there will be a "Debug" menu (ignore it for now; it's described in the documentation linked at the end of this page but you don't need to use it yet).
If you get to the website's front page but it doesn't finish loading 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 red "Clear Data" 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.
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.
It is also important that you read 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.
