Deploying Habitica

Introduction

Habitica is an open-source gamified habit tracker and productivity application that turns your real-life tasks and goals into an RPG adventure. By completing daily habits, to-dos, and goals, you earn experience points, gold, and equipment for your customizable avatar. The social features allow you to join parties, battle monsters with friends, and participate in guilds and challenges.

Built with Node.js and MongoDB, Habitica provides a unique approach to productivity by leveraging game mechanics to encourage positive habit formation. The application features a responsive web interface that works across all devices, making it easy to track your progress anywhere.

Key highlights of Habitica:

Gamified Productivity: Earn XP, gold, and rewards by completing real-life tasks and habits
Avatar Customization: Customize your character with equipment, pets, and mounts
Social Features: Join parties to battle bosses, participate in guilds, and complete challenges
Habit Tracking: Track daily habits with streaks and reminders
Task Management: Organize to-dos with priorities, due dates, and checklists
Mobile Apps: Native iOS and Android apps sync with your web account
Open Source: Self-host your own instance with full control over your data

This guide walks through deploying Habitica on Klutch.sh using Docker, configuring MongoDB for data persistence, and setting up the application for production use.

Prerequisites

Before deploying Habitica on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Habitica configuration
Basic familiarity with Docker and containerization concepts
A MongoDB database (can be deployed separately on Klutch.sh)
(Optional) SMTP credentials for email notifications

Preparing Your Repository

Create a GitHub repository with the following structure:

habitica-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in your repository:

FROM node:18-alpine

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Create app directory
WORKDIR /app

# Clone Habitica repository
RUN apk add --no-cache git python3 make g++ \
    && git clone --depth 1 https://github.com/HabitRPG/habitica.git . \
    && npm ci --only=production

# Build the application
RUN npm run build

# Expose the application port
EXPOSE 3000

# Start the application
CMD ["npm", "start"]

Alternatively, use a community-maintained Docker image:

FROM awinterstein/habitica-server:latest

# Set environment variables
ENV NODE_DB_URI=${NODE_DB_URI}
ENV BASE_URL=${BASE_URL}
ENV ADMIN_EMAIL=${ADMIN_EMAIL}

EXPOSE 3000

Environment Variables Reference

Variable	Required	Description
`NODE_DB_URI`	Yes	MongoDB connection string (e.g., `mongodb://mongo:27017/habitica`)
`BASE_URL`	Yes	Public URL of your Habitica instance
`ADMIN_EMAIL`	Yes	Administrator email address
`INVITE_ONLY`	No	Set to `true` to disable open registration
`EMAIL_SERVER_URL`	No	SMTP server hostname
`EMAIL_SERVER_PORT`	No	SMTP server port
`EMAIL_SERVER_AUTH_USER`	No	SMTP username
`EMAIL_SERVER_AUTH_PASSWORD`	No	SMTP password

Deploying Habitica on Klutch.sh

Set Up MongoDB Database

Habitica requires MongoDB for data storage. Deploy a MongoDB instance on Klutch.sh first, or use a managed MongoDB service. Note your connection string for the next steps.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Habitica deployment configuration"
git remote add origin https://github.com/yourusername/habitica-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “habitica” or similar.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Habitica repository.

Configure HTTP Traffic

Select HTTP as the traffic type
Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
`NODE_DB_URI`	Your MongoDB connection string
`BASE_URL`	`https://your-app-name.klutch.sh`
`ADMIN_EMAIL`	Your administrator email
`INVITE_ONLY`	`false` (set to `true` after initial setup)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/app/data`	5 GB	Application data and uploads

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Habitica with HTTPS enabled.

Access Habitica

Once deployment completes, access your Habitica instance at https://your-app-name.klutch.sh. Create your first user account to become the administrator.

Post-Deployment Configuration

Initial Setup

Navigate to your Habitica instance and create your first account
This account becomes the administrator
Configure site settings through the admin panel
Consider setting INVITE_ONLY=true to prevent open registration

Configuring Email Notifications

For password resets and notifications, configure SMTP:

Update your environment variables with SMTP credentials
Redeploy the application to apply changes
Test email delivery through the admin panel

Troubleshooting

Database Connection Issues

Verify your MongoDB connection string is correct
Ensure MongoDB is accessible from your Habitica container
Check that the database user has read/write permissions

Application Won’t Start

Review build logs in the Klutch.sh dashboard
Verify all required environment variables are set
Check that port 3000 is configured correctly

Additional Resources

Conclusion

Deploying Habitica on Klutch.sh provides a gamified productivity platform with automatic builds, persistent storage, and secure HTTPS access. The combination of RPG mechanics and task management creates an engaging way to build positive habits and stay productive. With your self-hosted instance, you maintain full control over your data while enjoying the social and motivational features that make Habitica unique.