Setting up Habitica Locally on Linux

Set Up a Swap File
If your computer does not have much RAM, 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). If you have a relatively new computer with good RAM, you can probably ignore this section.

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.

If you did have to create or increase a swap file, you would have needed to do that with sudo (preferred) or by logging in as the root user (not recommended for security). For the remainder of the instructions on this page, 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 Build Tools
''ALYS TODO: 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.''

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 MongoDB

 * 1) Install MongoDB in the appropriate way for your type of Linix. Note:
 * 2) * It is recommended that, where possible, you follow MongoDB's official instructions.
 * 3) * Official instructions for Linux: Install MongoDB Community Edition on Linux.
 * 4) ** For Linux, those instructions are broken down by distribution, so follow the appropriate link from that page. For CentOS, use the RedHat instructions.
 * 5) ** 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.
 * 6) Start the MongoDB server if it was not started during the installation process (the instructions above should tell you how).
 * 1) Start the MongoDB server if it was not started during the installation process (the instructions above should tell you how).

Install Node and NPM
This section takes you through the process of installing node and npm.

The node executable might be called nodejs on your system. _ALYS TODO: put instructions here for working out which you have then simplify the instructions below_


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


 * 1) *If that command shows that node/nodejs is not installed, proceed to the next step.
 * 2) *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 node for your flavour of Unix from the (NodeJS Downloads page, NodeSource Node.js binary distributions, or the Installing Node.js via package manager page.
 * 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 8 needs to be installed:


 * 1) *For CentOS 7, if Node 8 needs to be installed:


 * 1) Check that you installed node successfully and that it is the correct version:


 * 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 node 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 5 needs to be installed:

Install Other Generic Requirements
Install some npm packages globally: sudo npm install -g mocha

Install Habitica-Specific Requirements

 * 1) Install the Habitica-specific npm and bower packages: npm install
 * 2) *If you see errors related to,  , or  , it is possible that your system does not have tools for building software from source code. For Ubuntu and distributions based on it, you can install them using   although this isn't a common problem so it is recommended that you investigate first to see if this is needed or if there is some other cause for those errors. For CentOS, if it wasn't installed with developer tools, run  . For any other distribution, if installing those programs seems necessary, consult the distribution's documentation to find out how. After installing them, open a new terminal session and run   and the rest of the Habitica installation process there to use your system's new environment (  will probably still fail in your original terminal session). Be sure to   to the same directory you were in when you began the   command.
 * 3) *If "npm install" fails for other reasons, try rerunning it again two or three times in case the failures are from timeouts.