Deploy Habitica

Deploy and Host Habitica on Railway

Habitica turns the boring parts of a day into a role-playing game. Habits, dailies and to-dos sit on one board, and finishing them earns experience, gold and loot for a pixel-art avatar that levels up, learns a class and takes damage when you skip a daily. Open source since 2013, it is used by students, ADHD communities and anyone who has bounced off a plain checklist. Self-host Habitica to keep your task list and streak history on your own infrastructure.

This template deploys Habitica on Railway as three services. habitica builds the Node.js API and the Vue web client from upstream source and serves both on one public domain. mongo runs MongoDB 7 as a single-member replica set with keyfile authentication on a persistent volume — Habitica's change streams and transactions require one. Redis backs the API rate limiter. Only the app service is reachable publicly, and the site sits behind HTTP basic auth by default, because Habitica has no setting for closing registration.

Getting Started with Habitica on Railway

Deploy the template, then open the generated Railway domain. A browser prompt appears first: that is the site-wide gate, and its credentials are the SITE_HTTP_AUTH_USERNAMES and SITE_HTTP_AUTH_PASSWORDS variables on the habitica service; the password is generated at deploy time, so copy it from the variables panel. Past the gate you reach Habitica's sign-up page and create the first account with an email and password; there are no default credentials. Habitica then asks for a username, walks you through avatar creation and opens the task board.

Add a habit, a daily and a to-do, then tick one off — the experience bar and gold counter move immediately, which confirms the app is writing to MongoDB. To grant yourself the admin panel, set ADMIN_USERNAME to the username you chose; the container promotes that account on its next boot and an Admin entry appears in the navigation. Creating a party, and a challenge inside it, exercises MongoDB transactions end to end.

About Hosting Habitica

Habitica is a habit tracker, to-do list and daily planner wrapped in a lightweight RPG. Its premise is that a reward loop beats willpower: completed tasks pay experience and gold, missed dailies cost health, and gold buys equipment, pets and rewards you define yourself. Key features:

• Habits, dailies, to-dos and custom rewards on one board, with tags, checklists and due dates
• An avatar with health, experience, levels, classes, equipment, pets and mounts
• Parties and guilds for shared quests, plus challenges that push a task list to members
• A REST API (v3 and v4) with per-user keys, which community tools are built on
• Data export, and an admin panel for user support and moderation

The app service holds no state and can be redeployed freely; MongoDB owns everything durable on its volume, and Redis holds only rate-limiter counters.

Why Deploy Habitica on Railway

Habitica needs a MongoDB replica set, not just a MongoDB — the part most self-hosting guides get wrong.

• The database ships as a working single-member replica set with keyfile auth
• Persistent volume, health checks and restart policies are configured
• The app image builds from upstream source, so no unofficial container is involved
• One public domain, with the database and cache private
• Site-wide basic auth is on out of the box

Common Use Cases

• A private habit tracker for someone who would rather not keep task history on a third-party service
• A family running a shared party, where dailies and challenges are visible to everyone
• A study group or team using challenges to hold a routine together for a semester
• A sandbox for building against Habitica's API without touching a production account

Dependencies for Habitica

• habitica — Node.js 20 image built from HabitRPG/habitica, serving the Express API and compiled Vue client on one port
• mongo — mongo:7.0 with --replSet and a keyfile, on a 5 GB volume at /data/db
• Redis — redis:8.2, used only by the rate limiter

Habitica opens a change stream at startup and runs transactions when someone joins a challenge or a group, so a standalone MongoDB will not do. Without Redis the per-IP rate limiter cannot run, which matters as soon as the instance is reachable from the internet.

Environment Variables Reference

Deployment Dependencies

• Source: github.com/HabitRPG/habitica; deployment images: github.com/gridalpha/habitica-railway
• Runtime: Node.js 20, MongoDB 7.0, Redis 8
• Docs: habitica.fandom.com, plus /apidoc on your instance

Hardware Requirements for Self-Hosting Habitica

The first build is the heavy part — Babel for the server, Vite for the client — but the running app idles under 500 MB for one user.

Self-Hosting Habitica

Upstream ships a development compose file rather than a production image, so a local run starts the database as a replica set first. This starts MongoDB the way Habitica expects:

docker run -d --name habitica-mongo -p 27017:27017 \
  mongo:7.0 --bind_ip_all --replSet rs
docker exec habitica-mongo mongosh --quiet --eval \
  'rs.initiate({_id: "rs", members: [{_id: 0, host: "localhost:27017"}]})'

Then build and run the app from a checkout — Habitica reads configuration from the environment or a config.json in the repository root:

git clone https://github.com/HabitRPG/habitica.git && cd habitica
npm install && npm run postinstall
npm run client:build
NODE_ENV=production npx gulp build:prod
NODE_ENV=production PORT=3000 \
  BASE_URL=http://localhost:3000 \
  NODE_DB_URI="mongodb://localhost:27017/habitica?replicaSet=rs&directConnection=true" \
  SESSION_SECRET=change-me SESSION_SECRET_KEY=$(openssl rand -hex 32) \
  ENABLE_CONSOLE_LOGS_IN_PROD=true \
  node ./website/transpiled-babel/index.js

How Much Does Habitica Cost to Self-Host?

Habitica is free and open source, dual-licensed under GPL-3.0 and its own licence, so self-hosting adds no licence fee. Subscriptions and gems on habitica.com pay for the hosted service and cosmetics; on your own instance those features are present already. Railway charges for compute and storage only.

FAQ

What is Habitica?

Habitica is an open-source habit tracker and to-do list that scores real-life tasks as a role-playing game, with an avatar that gains experience and gold for finished tasks and loses health for missed ones.

What does this Railway template deploy?

Three services: the Habitica app built from upstream source, MongoDB 7 as a single-member replica set on a volume, and Redis for the API rate limiter.

Why does Habitica need a MongoDB replica set instead of a plain database?

Habitica watches a collection with a change stream at startup and wraps challenge joins, group changes and the daily cron in transactions. Neither works on a standalone mongod.

How do I make myself an admin on a self-hosted Habitica instance?

Set ADMIN_USERNAME on the habitica service to your username after registering. The container grants that account full admin permissions on its next boot and records that it has done so, so removing the permission later survives a redeploy.

Can I turn off the login prompt that appears before Habitica loads?

Yes — set SITE_HTTP_AUTH_ENABLED to false. Be deliberate: Habitica has no setting to close registration, so without that gate anyone who finds the URL can create an account.

Does password reset or email verification work on a self-hosted instance?

No. Habitica queues transactional email for a mail worker that is not part of the open-source deployment, so reset links are never delivered. Keep your credentials somewhere safe.

Can the official Habitica mobile apps connect to my own server?

No — they are pinned to habitica.com. Your instance is reachable from any browser and through its REST API, which community tools use.