Skip to content

Installation Guide

Jump to bottom
Dinesh Dawonauth edited this page Jul 22, 2025 · 2 revisions

This guide will help you set up My Progress Planner for local development.

📋 Prerequisites

Before you begin, ensure you have the following installed:

Required Software

  • Node.js ≥ 18.17.0 (LTS recommended)
  • npm ≥ 9.0.0 or yarn ≥ 1.22.0
  • Git for version control

External Services

  • Supabase account and project
  • OpenAI API account with GPT-4 access

Verification

# Check Node.js version
node --version

# Check npm version
npm --version

# Check Git version
git --version

🚀 Quick Installation

1. Clone the Repository

git clone https://github.com/dinesh-git17/my-progress-planner.git
cd my-progress-planner

2. Install Dependencies

# Using npm (recommended)
npm install

# Or using yarn
yarn install

3. Environment Setup

Copy the example environment file:

cp .env.example .env.local

4. Configure Environment Variables

Edit .env.local with your actual values:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

# OpenAI Integration
OPENAI_API_KEY=sk-your_openai_api_key_here

# Security (Generate strong passwords)
CRON_SECRET=your_secure_random_string
ADMIN_PASSWORD=your_secure_admin_password

# Optional: Push Notifications
VAPID_PUBLIC_KEY=your_vapid_public_key
VAPID_PRIVATE_KEY=your_vapid_private_key
PUSH_CONTACT_EMAIL=mailto:[email protected]

5. Database Setup

Run the database setup (see Database Schema for details):

npm run db:setup

6. Start Development Server

npm run dev

Visit http://localhost:3000 to see your app running! 🎉

🔧 Detailed Setup

Supabase Configuration

  1. Create a new Supabase project at supabase.com
  2. Get your credentials:
    • Go to Settings → API
    • Copy URL and anon key
    • Copy service_role key (keep this secret!)
  3. Set up authentication:
    • Go to Authentication → Settings
    • Configure providers (Google OAuth recommended)
  4. Import database schema (see Database Schema)

OpenAI API Setup

  1. Create an OpenAI account at platform.openai.com
  2. Generate an API key:
    • Go to API Keys section
    • Create new secret key
    • Copy the key (starts with sk-)
  3. Ensure GPT-4 access (may require payment method)

Development Tools (Optional)

Install additional development tools:

# TypeScript language server
npm install -g typescript

# ESLint for code quality
npm run lint

# Prettier for code formatting
npm run format

🧪 Verify Installation

Run Tests

# Unit tests
npm test

# Type checking
npm run type-check

# Build verification
npm run build

Check Key Features

  • ✅ App loads at localhost:3000
  • ✅ Authentication works (try Google login)
  • ✅ Database connection established
  • ✅ AI responses generate properly
  • ✅ PWA features work (try going offline)

🛠️ Available Scripts

Script Description
npm run dev Start development server with hot reload
npm run build Create production build
npm run start Start production server
npm run lint Run ESLint for code quality
npm run type-check Run TypeScript compiler check
npm run test Run test suite
npm run clean Clear Next.js cache

📁 Project Structure

my-progress-planner/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── (auth)/            # Authentication routes
│   │   ├── api/               # API endpoints
│   │   ├── breakfast/         # Meal logging pages
│   │   ├── lunch/
│   │   ├── dinner/
│   │   └── summaries/         # Daily summaries
│   ├── components/            # Reusable React components
│   ├── lib/                   # Utility functions
│   └── types/                 # TypeScript definitions
├── public/                    # Static assets
│   ├── icons/                 # PWA icons
│   ├── splash/               # iOS splash screens
│   └── manifest.json         # PWA manifest
├── .env.example              # Environment template
├── next.config.mjs           # Next.js configuration
├── tailwind.config.ts        # Tailwind CSS config
└── tsconfig.json             # TypeScript config

🚨 Troubleshooting

Common Issues

Node.js version issues:

# Install Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 18
nvm install 18
nvm use 18

Port already in use:

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
npm run dev -- -p 3001

Environment variables not loading:

  • Ensure .env.local exists in root directory
  • Restart development server after changes
  • Check for typos in variable names

Database connection issues:

  • Verify Supabase URL and keys
  • Check project status in Supabase dashboard
  • Ensure database schema is properly set up

OpenAI API issues:

  • Verify API key format (starts with sk-)
  • Check billing and usage limits
  • Ensure GPT-4 access is enabled

✅ Next Steps

Once installation is complete:

  1. Read the Configuration guide for advanced setup
  2. Follow the Quick Start Tutorial to understand core features
  3. Review the Development Workflow for contributing guidelines
  4. Explore the API Documentation for customization

📞 Need Help?

Clone this wiki locally