417 lines
13 KiB
Markdown
417 lines
13 KiB
Markdown
# HabitForge 🎯
|
|
|
|
HabitForge is a powerful, self-hosted habit tracking and gamification platform designed to help users build and maintain consistent routines. It combines a robust Python backend with a dynamic, modern frontend to provide a premium user experience.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 📖 Overview
|
|
|
|
HabitForge allows users to create custom challenges (daily, weekly, monthly), track their progress with detailed analytics, and stay motivated through gamification elements like badges and streaks. The application is built with a **Mobile-First** design philosophy, ensuring a seamless experience across all devices.
|
|
|
|
### Key Features
|
|
|
|
* **🏆 Gamification:** Earn badges for streaks, total reps, and consistency.
|
|
* **📊 Analytics:** Visual charts (reps, completion rates) and consistency heatmaps.
|
|
* **🔁 Flexible Challenges:** Support for Daily, Weekly (specific days), and Monthly targets.
|
|
* **🧠 Smart Tracking:** Tracks reps, completion status, and optional notes per day.
|
|
* **🌗 Dark Mode:** Fully supported dark/light themes with persistence.
|
|
* **📱 Responsive UI:** Built with Tailwind CSS for a fluid experience on mobile and desktop.
|
|
* **🔐 Authentication:** Secure JWT-based user authentication system.
|
|
* **🖱️ Drag & Drop:** Reorder challenges easily to prioritize your focus.
|
|
|
|
---
|
|
|
|
## 🛠 Tech Stack
|
|
|
|
### Backend
|
|
* **Framework:** [FastAPI](https://fastapi.tiangolo.com/) (High performance, easy to learn)
|
|
* **Database ORM:** [SQLAlchemy](https://www.sqlalchemy.org/)
|
|
* **Database:** SQLite (Default, stored in `./data/habitforge.db`)
|
|
* **Authentication:** OAuth2 with Password (and hashing via Argon2/Passlib)
|
|
* **Schema Validation:** Pydantic Models
|
|
|
|
### Frontend
|
|
* **Core:** Vanilla JavaScript (ES6+)
|
|
* **Styling:** [Tailwind CSS](https://tailwindcss.com/) (via CDN for simplicity)
|
|
* **Icons:** FontAwesome 6
|
|
* **Animations:** Anime.js
|
|
* **Charts:** Chart.js
|
|
* **Drag & Drop:** SortableJS
|
|
|
|
### Infrastructure
|
|
* **Containerization:** Docker & Docker Compose
|
|
* **Server:** Uvicorn (ASGI)
|
|
|
|
---
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
Before you begin, ensure you have the following installed:
|
|
* **Docker** and **Docker Compose**
|
|
* **Python 3.9+** (if running locally without Docker)
|
|
* **Google OAuth Credentials** (optional, for health metrics sync)
|
|
|
|
#### Environment Setup
|
|
HabitForge uses environment variables for configuration.
|
|
1. **Copy the example file:**
|
|
```bash
|
|
cp .env.example .env.development
|
|
# Also create production if needed
|
|
cp .env.example .env.production
|
|
```
|
|
2. **Edit the files:** Fill in your `SECRET_KEY` and Google API credentials.
|
|
|
|
---
|
|
|
|
### 🐳 Running with Docker (Recommended)
|
|
|
|
HabitForge provides several Docker Compose configurations depending on your needs:
|
|
|
|
#### 1. Simple Mode (SQLite)
|
|
Perfect for a quick test or personal use with zero database configuration.
|
|
```bash
|
|
# Uses docker-compose.yml
|
|
docker-compose up -d --build
|
|
```
|
|
* **Database:** SQLite stored in `./data/habitforge.db`
|
|
* **Access:** `http://localhost:8000`
|
|
|
|
#### 2. Development Mode (PostgreSQL)
|
|
Ideal for development with a robust database and hot-reloading enabled.
|
|
```bash
|
|
# Uses docker-compose.dev.yml
|
|
docker-compose -f docker-compose.dev.yml up -d --build
|
|
```
|
|
* **Database:** PostgreSQL 15
|
|
* **Features:** Auto-reload enabled in the backend.
|
|
* **Access:** `http://localhost:8000`
|
|
|
|
#### 3. Production Mode (Full Stack)
|
|
The professional setup with security and performance in mind.
|
|
```bash
|
|
# Uses docker-compose.prod.yml
|
|
docker-compose -f docker-compose.prod.yml up -d --build
|
|
```
|
|
* **Components:**
|
|
* **Nginx:** Reverse proxy with SSL/TLS support.
|
|
* **Gunicorn:** Production-grade WSGI server with multiple workers.
|
|
* **PostgreSQL:** Dedicated database container.
|
|
* **Backup:** Automatic daily database backups to `./backups`.
|
|
* **Access:** `http://localhost` (or your configured domain)
|
|
|
|
---
|
|
|
|
### 🐍 Local Development (Manual)
|
|
|
|
If you prefer to run the services directly on your machine:
|
|
|
|
1. **Set up Python Environment:**
|
|
```bash
|
|
python -m venv venv
|
|
# Windows
|
|
.\venv\Scripts\activate
|
|
# Linux/Mac
|
|
source venv/bin/activate
|
|
```
|
|
|
|
2. **Install Dependencies:**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Run the Server:**
|
|
```bash
|
|
# Ensure your .env file is present or env vars are set
|
|
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
---
|
|
|
|
## 📂 Project Structure
|
|
|
|
```plaintext
|
|
HabitForge/
|
|
├── backend/ # Python FastAPI Backend (Modular Architecture)
|
|
│ ├── api/v1/ # API Routes (Auth, Challenges, Health)
|
|
│ ├── core/ # Configuration, Security, Dependencies
|
|
│ ├── models/ # SQLAlchemy Database Models
|
|
│ ├── schemas/ # Pydantic Validation Schemas
|
|
│ ├── services/ # Business Logic Layer
|
|
│ ├── repositories/ # Data Access Layer
|
|
│ └── integrations/ # External APIs (Google Fit, Zepp)
|
|
├── frontend/ # Static Frontend Assets
|
|
│ ├── app.js # Main frontend logic
|
|
│ └── index.html # Dashboard
|
|
├── data/ # SQLite storage (if used)
|
|
├── nginx/ # Nginx configuration and SSL certificates
|
|
├── scripts/ # Database migrations and backup scripts
|
|
├── docker-compose.yml # Simple SQLite configuration
|
|
├── docker-compose.dev.yml # Development (Postgres) configuration
|
|
└── docker-compose.prod.yml # Production (Nginx + Postgres + Backup) configuration
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 API Documentation
|
|
|
|
Once the server is running, you can access the automatic interactive API documentation provided by Swagger UI:
|
|
* **Docs:** `http://localhost:8000/docs`
|
|
* **Redoc:** `http://localhost:8000/redoc`
|
|
|
|
### Core Endpoints
|
|
* **Auth:** `/api/auth/register`, `/api/auth/token`
|
|
* **Challenges:**
|
|
* `GET /api/challenges`: List all user challenges
|
|
* `POST /api/challenges`: Create new challenge
|
|
* `PUT /api/challenges/reorder`: Update display order
|
|
* **Tracking:**
|
|
* `POST /api/tracking`: Log reps/completion for a date
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
All configuration is managed via Environment Variables or a `.env` file.
|
|
|
|
| Variable | Description | Default |
|
|
| :--- | :--- | :--- |
|
|
| `SECRET_KEY` | Key for JWT encryption | *Required* |
|
|
| `DATABASE_URL` | SQLAlchemy connection string | `sqlite:///./data/habitforge.db` |
|
|
| `CORS_ORIGINS` | Allowed origins for API | `http://localhost:8000` |
|
|
| `GOOGLE_CLIENT_ID` | Google OAuth Client ID | `""` |
|
|
| `GOOGLE_CLIENT_SECRET` | Google OAuth Client Secret | `""` |
|
|
|
|
---
|
|
|
|
## 🔐 Google OAuth Setup (Health Metrics Integration)
|
|
|
|
To enable Google Fit integration for health metrics tracking, you need to create OAuth 2.0 credentials in the Google Cloud Console.
|
|
|
|
### Step 1: Create a Google Cloud Project
|
|
|
|
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
|
2. Click **"Select a project"** → **"New Project"**
|
|
3. Enter a project name (e.g., "HabitForge")
|
|
4. Click **"Create"**
|
|
|
|
### Step 2: Enable Required APIs
|
|
|
|
1. In your project, navigate to **"APIs & Services"** → **"Library"**
|
|
2. Search for and enable the following APIs:
|
|
- **Google Fitness API**
|
|
- **Google OAuth2 API** (usually enabled by default)
|
|
|
|
### Step 3: Configure OAuth Consent Screen
|
|
|
|
1. Go to **"APIs & Services"** → **"OAuth consent screen"**
|
|
2. Select **"External"** (unless you have a Google Workspace)
|
|
3. Fill in the required information:
|
|
- **App name:** HabitForge
|
|
- **User support email:** Your email
|
|
- **Developer contact:** Your email
|
|
4. Click **"Save and Continue"**
|
|
5. **Scopes:** Click **"Add or Remove Scopes"** and add:
|
|
- `.../auth/fitness.activity.read`
|
|
- `.../auth/fitness.body.read`
|
|
- `.../auth/fitness.heart_rate.read`
|
|
- `.../auth/fitness.sleep.read`
|
|
6. Click **"Save and Continue"**
|
|
7. **Test users:** Add your Google account email (for testing)
|
|
8. Click **"Save and Continue"**
|
|
|
|
### Step 4: Create OAuth 2.0 Credentials
|
|
|
|
1. Go to **"APIs & Services"** → **"Credentials"**
|
|
2. Click **"+ Create Credentials"** → **"OAuth client ID"**
|
|
3. Select **"Web application"**
|
|
4. Configure:
|
|
- **Name:** HabitForge Web Client
|
|
- **Authorized JavaScript origins:**
|
|
```
|
|
http://localhost:8000
|
|
https://yourdomain.com
|
|
```
|
|
- **Authorized redirect URIs:**
|
|
```
|
|
http://localhost:8000/api/google/callback
|
|
https://yourdomain.com/api/google/callback
|
|
```
|
|
5. Click **"Create"**
|
|
6. **Copy your credentials:**
|
|
- `GOOGLE_CLIENT_ID`: The Client ID (looks like `xxxxx.apps.googleusercontent.com`)
|
|
- `GOOGLE_CLIENT_SECRET`: The Client Secret
|
|
|
|
### Step 5: Update Your .env File
|
|
|
|
Add the credentials to your `.env` file:
|
|
|
|
```bash
|
|
GOOGLE_CLIENT_ID=your-client-id-here.apps.googleusercontent.com
|
|
GOOGLE_CLIENT_SECRET=your-client-secret-here
|
|
```
|
|
|
|
### Step 6: Test the Integration
|
|
|
|
1. Restart your application
|
|
2. Navigate to the Health Dashboard
|
|
3. Click the **"Sync"** button
|
|
4. Authorize HabitForge to access your Google Fit data
|
|
5. Data should sync automatically
|
|
|
|
---
|
|
|
|
## 🗄️ Database Configuration
|
|
|
|
HabitForge supports two database backends: **SQLite** (default, simple) and **PostgreSQL** (production-ready).
|
|
|
|
### Option 1: SQLite (Default - Recommended for Personal Use)
|
|
|
|
SQLite requires **no additional setup** and is perfect for single-user deployments.
|
|
|
|
**Configuration:**
|
|
```bash
|
|
# .env file
|
|
DATABASE_URL=sqlite:///./data/habitforge.db
|
|
```
|
|
|
|
**Characteristics:**
|
|
- ✅ Zero configuration required
|
|
- ✅ File-based (stored in `./data/habitforge.db`)
|
|
- ✅ Perfect for personal use
|
|
- ✅ Automatic backups via file copy
|
|
- ⚠️ Not recommended for high-concurrency scenarios
|
|
|
|
**Docker Compose:**
|
|
```bash
|
|
# Uses SQLite by default
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
### Option 2: PostgreSQL (Recommended for Production)
|
|
|
|
PostgreSQL provides better performance, concurrency, and scalability.
|
|
|
|
#### A. Using Docker Compose (Easiest)
|
|
|
|
**Development Mode:**
|
|
```bash
|
|
# Uses docker-compose.dev.yml with PostgreSQL
|
|
docker-compose -f docker-compose.dev.yml up -d --build
|
|
```
|
|
|
|
**Production Mode:**
|
|
```bash
|
|
# Uses docker-compose.prod.yml with PostgreSQL + Nginx
|
|
docker-compose -f docker-compose.prod.yml up -d --build
|
|
```
|
|
|
|
The database credentials are configured in the respective `docker-compose` files.
|
|
|
|
#### B. Using External PostgreSQL Server
|
|
|
|
If you have an existing PostgreSQL server:
|
|
|
|
1. **Create a database:**
|
|
```sql
|
|
CREATE DATABASE habitforge;
|
|
CREATE USER habitforge_user WITH PASSWORD 'your_secure_password';
|
|
GRANT ALL PRIVILEGES ON DATABASE habitforge TO habitforge_user;
|
|
```
|
|
|
|
2. **Configure DATABASE_URL:**
|
|
```bash
|
|
# .env file
|
|
DATABASE_URL=postgresql://habitforge_user:your_secure_password@localhost:5432/habitforge
|
|
```
|
|
|
|
**Format:**
|
|
```
|
|
postgresql://[username]:[password]@[host]:[port]/[database_name]
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Local PostgreSQL
|
|
DATABASE_URL=postgresql://postgres:password@localhost:5432/habitforge
|
|
|
|
# Remote PostgreSQL
|
|
DATABASE_URL=postgresql://user:[email protected]:5432/habitforge
|
|
|
|
# With SSL
|
|
DATABASE_URL=postgresql://user:[email protected]:5432/habitforge?sslmode=require
|
|
```
|
|
|
|
3. **Run migrations:**
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
#### C. PostgreSQL on Cloud Providers
|
|
|
|
**Heroku Postgres:**
|
|
```bash
|
|
DATABASE_URL=postgresql://user:[email protected]:5432/dbname
|
|
```
|
|
|
|
**AWS RDS:**
|
|
```bash
|
|
DATABASE_URL=postgresql://username:[email protected]:5432/habitforge
|
|
```
|
|
|
|
**Google Cloud SQL:**
|
|
```bash
|
|
DATABASE_URL=postgresql://user:pass@/dbname?host=/cloudsql/project:region:instance
|
|
```
|
|
|
|
**DigitalOcean Managed Database:**
|
|
```bash
|
|
DATABASE_URL=postgresql://user:[email protected]:25060/habitforge?sslmode=require
|
|
```
|
|
|
|
### Switching Between Databases
|
|
|
|
To switch from SQLite to PostgreSQL (or vice versa):
|
|
|
|
1. **Update DATABASE_URL** in your `.env` file
|
|
2. **Run migrations:**
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
3. **Restart the application:**
|
|
```bash
|
|
docker-compose down
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
**Note:** Data is **not automatically migrated** between databases. You'll need to export/import data manually if switching with existing data.
|
|
|
|
---
|
|
|
|
### Database Migrations
|
|
The project includes Alembic for database version control.
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome!
|
|
1. Fork the project.
|
|
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
|
|
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
|
|
4. Push to the branch (`git push origin feature/AmazingFeature`).
|
|
5. Open a Pull Request.
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
Distributed under the MIT License. See `LICENSE` for more information.
|