|Note this article is still under construction|
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 Docker. If you are not using Docker, 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.
- what version of Docker you are using and what OS you are running it on
- 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.
git on your machine (installation instructions available here).
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 root. When elevated permissions are needed, this page will tell you to use sudo. 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.
- 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.
- 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.
- 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:
Remain in that directory for all future steps on this page, unless advised otherwise.
- Configure Git to sync your fork with Habitica's repository.
git remote add upstream https://github.com/HabitRPG/habitica.git
- Verify that everything is set up properly by typing
git remote -vwhich 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:
cp config.json.example config.json
If desired, edit
- 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
config.jsonand 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
- Follow Docker's official instructions for installing docker and docker-compose.
- Verify your installation by clicking the Docker Quickstart Terminal icon on your Desktop (Windows) or Launchpad (Mac OS X).
- In the Docker Quickstart Terminal, cd to Habitica's top-level directory (the one that contains the
config.json.examplefile). Remain in that directory for all future steps on this page, unless advised otherwise.
Use docker-compose to Build and Start Docker ContainersEdit
Run this command:
docker-compose up -d
That command will use Habitica's docker-compose.yml file to build Docker containers to run the various parts of a Habitica install: the server, the website client, and a MongoDB database server. All software needed for those contains will be installed automatically during the build process.
After the build is complete, if you wish to see the technical details of the three containers, you can run this command:
At this point, the version of Habitica running in the containers is the develop branch of the Habitica repository. It is not your local clone of your fork of the repository. This is not the best way to run Habitica locally because any changes you make to the code in the container will be lost when the container is shut down and you will not be able to easily push them to your fork of the repository. The next section will fix these problems.
Mount your Local Clone in the ContainersEdit
This section will mount your local clone of the Habitica repository in the containers, which is safer and more convenient.
- Stop the containers by running:
- Mount your local clone directory to the habitica_client container and bootstrap:
docker run -t --volume `pwd`:/usr/src/habitrpg habitica_client npm install
- Run the containers using the local clone:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
At this point, the version of Habitica running in the containers is the version that exists in your local clone of your fork of the repository. You can use git installed on your computer to create new branches in your local clone (i.e., do not use git in the container to create branches). You can used any text editor or IDE installed on your computer to edit Habitica's code (i.e., you do not have to use an editor in the container). When you make changes to the code in your local clone of the repository, those changes will be visible in the Habitica website served via the containers. You can manually test your changes using that website as described below.
(NB: When you are ready to run Habitica's automatic test suite as described in Using Your Local Install to Modify Habitica's Website and API, that page will show you how to create another Docker container for running the tests.)
Review the Server OutputEdit
To view the output from the Habitica webserver, run
docker-compose logs server and to view the output from building the website client, run
docker-compose logs client
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).
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.