HabitTrove is a gamified habit tracking application that helps you build and maintain positive habits by rewarding you with coins, which you can use to exchange for rewards.

Differences to Upstream

I generally try to keep the main branch up to date with upstream features, merging tagged versions and mapping them to <upstream-version>.0.

In this version I've taken steps to ensure a smoother experience and decreased the chance of the program bricking itself. This doesn't mean that it's completely stable, but I've fixed the most glaring bugs I encountered.

Differences (as of writing) are:

resolved linting problems so you can actually commit things
added missing dependency
refactored adding habit modal to cause less errors
resolved undefined error
replaced dockerhub release flow with github
miscellaneous refactorings
split habits & tasks page into two different pages
only display "show all" if there are more than 4 entries

Features

🎯 Create and track daily habits
🏆 Earn coins for completing habits
💰 Create a wishlist of rewards to redeem with earned coins
📊 View your habit completion streaks and statistics
✏️ Add freehand drawings to habits and wishlist items for visual reminders
📅 Calendar heatmap to visualize your progress (WIP)
🌍 Multi-language support (English, Español, Català, Deutsch, Français, Русский, 简体中文, 한국어, 日本語)
🌙 Dark mode support
📲 Progressive Web App (PWA) support
💾 Automatic daily backups with rotation

Usage

Creating Habits: Click the "Add Habit" button to create a new habit. Set a name, description, and coin reward.
Tracking Habits: Mark habits as complete on your dashboard. Each completion earns you the specified coins.
Wishlist: Add rewards to your wishlist that you can redeem with earned coins.
Statistics: View your progress through the heatmap and streak counters.

Docker Deployment

HabitTrove can be run using Docker in several ways, depending on your needs:

Using Pre-built Images

The easiest way to run HabitTrove is using our pre-built Docker images from DockerHub:

First, prepare the data directory with correct permissions:

mkdir -p data backups
chown -R 1001:1001 data backups # Required for the nextjs user in container

Then run using either method:

# Generate a secure authentication secret
export AUTH_SECRET=$(openssl rand -base64 32)
echo $AUTH_SECRET

# Using docker-compose (recommended)
## Update the AUTH_SECRET environment variable in docker-compose.yaml
nano docker-compose.yaml
## Start the container
docker compose up -d

# Or using docker run directly
docker run -d \
  -p 3000:3000 \
  -v ./data:/app/data \
  -v ./backups:/app/backups \ # Add this line to map the backups directory
  -e AUTH_SECRET=$AUTH_SECRET \
  ghcr.io/manindark/habittrove

Available image tags:

latest: Stable release version, recommended for most users
vX.Y.Z (e.g., v0.1.4): Specific version for reproducible deployments and rollbacks
dev: Latest development build from the main branch, may contain unstable features

Choose your tag based on needs:

Use latest for general production use
Use version tags (e.g., v0.2.9) for reproducible deployments
Use dev for testing new features

Note on Volumes: The application stores user data in /app/data and backups in /app/backups inside the container. The examples above map ./data and ./backups from your host machine to these container directories. Ensure these host directories exist and have the correct permissions (chown -R 1001:1001 data backups).

Building Locally

If you want to build the image locally (useful for development):

# Build the Docker image
npm run docker-build

# Run the container
npm run docker-run

The application data will be persisted in the data directory in both cases.

Building the Project

To contribute to HabitTrove, you'll need to set up a development environment. Here's how to get started:

Prerequisites

Node.js 20 or later
npm package manager
Git (for version control)
bun (for running tests)

Setting Up the Development Environment

Clone the repository and navigate to the project directory:

git clone https://github.com/ManInDark/HabitTrove.git
cd habittrove

Install project dependencies:

npm install --force

Set up the development environment:

npm run setup:dev

Start the development server:

npm run dev

Open http://localhost:3000 in your browser to access the development version.

Running Tests

Before contributing, make sure to run the test suite:

npm test

Building for Production

To build the project for production:

npm run build

This will create an optimized production build in the .next directory.

Code Quality Tools

The project uses several tools to maintain code quality:

ESLint for linting: npm run lint
TypeScript type checking: npm run typecheck

Run these commands regularly during development to catch issues early.

Contributing

We welcome feature requests and bug reports! Please open an issue.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.