FANDOM


IMPORTANT NOTICE FOR ALL DEVELOPERS:

If your local install was made before 24 April 2018, the database needs to be updated. See the "Updating Your Local Install" section in Using Your Local Install to Modify Habitica's Website and API




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), please refer to Setting up Habitica Locally. This page is not relevant for contributing to development for the mobile apps.

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.

Prepare for Troubleshooting Edit

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

  • 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
  • links to your uploaded file(s)
  • what problem you're experiencing

Install Git Edit

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

Install git on your machine (installation instructions available here). These steps are taken from the git installation instructions above. There are multiple ways to install git on Windows. Listed below are the two easiest ways:

  • Download the most official build on the Git website . This download will start automatically.

Or

  • Download GitHub Desktop. This also includes the command line version of Git.

IMPORTANT! Edit

Windows Git Setup

Configuring the line ending conversions

When presented with the "Configuring the line ending conversions" window, 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
git config --global core.autocrlf input

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

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.

Putting Git in your PATH VariableEdit

It is important that the location of git is added to your PATH environment variable. The git installer might give you an option to do that. If it doesn't, after git is installed, find where the executable file has been placed and add that directory to your PATH variable in the standard way for modifying the PATH on Windows. If you need help with this, ask in the Aspiring Blacksmiths guild. If you are aware of the best way to ensure that the PATH is modified appropriately, please update these instructions.

Setting the PATH for Windows 10 Users  Edit

  1. Go to the Control Panel (aka Windows Settings), type 'environment variables' into the search field.
  2. Select Edit the System Environment Variables, and then click the Environment Variables button at the bottom of the System Properties dialog box. 
  3. Select Path, click Edit, and then add the line for Git (default installation: C:\Program Files\Git\bin) to a new line.   
  4. Click OK to save the path addition. 

To ensure that git is in your path. Open a windows command prompt and type git --help

Press Enter and if you see a list of available git commands then you have added git to the path properly.

Install Build ToolsEdit

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.

Install MongoDBEdit

Follow the MongoDB's official instructions to install MongoDB Community Edition on Windows (version 3.4).

It is important to follow the instructions for how to setup MongoDB from the above link. Steps below are an excerpt from the above. The first step provides quick access to the correct Downloads page.

IMPORTANT!

You must install version 3.4 (later versions will give you errors because they don't have the $pushall operator, which is used by Habitica's dependencies).

  1. You can download older versions of MongoDB here.
  2. Make sure to choose version 3.4.18 from the version drop down box.
  3. Choose your OS and system architecture. For example: Windows 64-bit x64
  4. Run the MongoDB.msi file which is probably located in your Downloads folder
  5. After MongoDB has downloaded and installed and if it wasn't started automatically at the end of installation you can start it by:
    • Command Prompt: Navigating to the directory where it was stored (C:\Program Files\MongoDB\Server\3.4\bin.) and run mongod.exe
    • Or by double clicking on the mongod.exe file if using the Windows File Explorer.
      Mongo previous

      Where to find the Previous Release link.

Start the MongoDB server if it was not started during the installation process (the instructions above should tell you how).

Install Node and NPMEdit

  1. Download and run the latest Node.js msi installation file. Important: You must install node 10 and npm 6. You will experience errors if you use any other 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.
  2. Launch a command window as Administrator and in that window:
    1. 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
    2. 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 5 needs to be installed:
        npm install -g npm@5

Install Other Generic RequirementsEdit

Launch a command window as Administrator.

Execute this command:
npm install -g mocha

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 HabiticaEdit

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)

Remain in the Correct Branch and DirectoryEdit

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 ConfigurationEdit

Create the config.json configuration file by copying (not renaming) the example one:
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 line saying "PORT":3000, in config.json and change the port to a suitable number.
  • 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.
  • 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 RequirementsEdit

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, the npm install command might not have run correctly. You can seek help in the Aspiring Blacksmiths (Habitica Coders) guild.

Start the Habitica Web ServerEdit

  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. In one command prompt or terminal, start the Habitica web server with:
    npm start
  4. In a second 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.
  5. Review the output of both of those commands as described below.

Review the Server OutputEdit

Blacksmiths setting up npm start output

Normal output from the server.

The output from starting the server (from the npm start command) typically looks something like the image to the right. You are likely to see slight differences in your system (e.g., different dates, times, version numbers).
Blacksmiths setting up npm run client dev output

Normal output from website client.

The inital output from building the website client (from the npm run client:dev command) typically looks something like the image to the right and there will probably be a pause of at least several seconds before additional output appears, if any. As long as the additional output does not contain obvious error messages, everything is probably fine.

Significant differences to those screenshots might indicate a problem.

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 at the top of this page.

If the outputs from both 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 BrowserEdit

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.

Next Steps: Using Your Local InstallEdit

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

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.