Setting Up Habitica for Local Development

Production Habitica runs on Ubuntu Linux, so these instructions are for similar environments, i.e., Debian-based Linux distros. Running Habitica on other architectures, like Windows, may require additional setup not documented here.

1. Install system packages: sudo apt install -y curl git libkrb5-dev
2. install libssl-1.1:
   • wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
   • sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
3. Install Node Version Manager: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
4. Restart your terminal session, then nvm install 20
5. Clone the Habitica repository and install dependencies:
   • git clone https://github.com/HabitRPG/habitica
   • cd habitica
   • npm i
   • cp config.json.example config.json

When you're ready to start a Habitica webserver:

1. npm run mongo:dev
   • If this command fails on your system, you may need to install MongoDB Community Server. Then instead of npm run mongo:dev, use sudo service mongod start.
2. In a separate terminal session, npm start
   • If the process silently halts, throws EPIPE errors, etc., your system may not have sufficient RAM. Check your swap file size and increase it to at least 4 GB.
   • You may additionally need to increase the file watchers limit: echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/50-max-user-watches.conf && sudo sysctl --system
3. In a third terminal session, npm run client:dev
4. Visit http://localhost:8080 in your browser and get started by setting up a Habitica account on your local site!

Most code changes will result in the process automatically restarting, such that a browser refresh will show your work live. Some files in website/common, notably website/common/locales, may require you to halt and restart the Express server (the npm start session).