academic_project_tracker

🚀 Installation Guide

Complete installation instructions for Research Project Tracker.

System Requirements

Minimum Requirements

• Node.js: v16.0.0 or higher
• npm: v7.0.0 or higher (comes with Node.js)
• Disk Space: 100MB
• RAM: 512MB
• OS: Windows 10+, macOS 10.15+, or Linux

Recommended

• Node.js: v18.0.0 or higher
• RAM: 1GB+
• Modern browser: Chrome, Firefox, Safari, or Edge (latest version)

Quick Installation

# 1. Clone the repository
git clone https://github.com/yourusername/project_tracker.git
cd project_tracker

# 2. Install all dependencies
npm install
cd src/frontend && npm install && cd ../..

# 3. Start the application
npm run dev

Open your browser to http://localhost:5173

Detailed Installation

Step 1: Install Node.js

macOS

# Using Homebrew
brew install node

# Or download from nodejs.org

Windows

1. Download installer from nodejs.org
2. Run installer
3. Verify: node --version

Linux (Ubuntu/Debian)

# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version
npm --version

Step 2: Get the Code

Option A: Git Clone (Recommended)

git clone https://github.com/yourusername/project_tracker.git
cd project_tracker

Option B: Download ZIP

1. Go to GitHub repository
2. Click “Code” → “Download ZIP”
3. Extract to desired location
4. Open terminal in extracted folder

Step 3: Install Dependencies

# Install backend dependencies
npm install

# Install frontend dependencies
cd src/frontend
npm install
cd ../..

Note: This may take a few minutes on first install.

Step 4: Start the Application

# Development mode (hot reload)
npm run dev

# Or run backend and frontend separately
npm run dev:backend  # In one terminal
npm run dev:frontend # In another terminal

Step 5: Access the Application

Open your browser to:

• Frontend: http://localhost:5173
• Backend API: http://localhost:5050/api/health

First-Time Setup

Option 1: Start Fresh

The app will create an empty database automatically. Just start adding projects!

Option 2: Use Student Template

npm run setup:student

This creates:

• 3 starter projects
• 6 useful tags
• Monthly and semester goals
• Sample tasks

Configuration

Change Ports

Edit .env file (create if doesn’t exist):

# Backend port (default: 5050)
PORT=5050

# Database location (default: src/backend/data/tracker.db)
DATABASE_PATH=src/backend/data/tracker.db

Database Location

By default, database is at: src/backend/data/tracker.db

To change location, set DATABASE_PATH in .env.

Production Build

# Build frontend
npm run build

# Start production server
NODE_ENV=production npm start

Platform-Specific Notes

macOS

• May need to allow app in Security & Privacy settings
• Recommended: Use Homebrew for Node.js
• Works on Apple Silicon (M1/M2) and Intel

Windows

• May need to run PowerShell as Administrator for global npm packages
• If you get permission errors, try: npm install --no-optional
• Use PowerShell or Git Bash (not CMD)

Linux

• May need sudo for global npm packages
• Debian/Ubuntu: Install build essentials if compilation fails

  sudo apt-get install build-essential
  

Troubleshooting

Port Already in Use

# Find and kill process on port 5050 or 5173
# macOS/Linux:
lsof -ti:5050 | xargs kill -9
lsof -ti:5173 | xargs kill -9

# Windows:
netstat -ano | findstr :5050
taskkill /PID <process_id> /F

Permission Errors

# Clear npm cache
npm cache clean --force

# Reinstall with clean slate
rm -rf node_modules package-lock.json
npm install

Module Not Found

# Make sure both backend and frontend dependencies are installed
npm install
cd src/frontend && npm install && cd ../..

Database Errors

# Reset database (WARNING: Deletes all data)
rm src/backend/data/tracker.db
npm run dev  # Will create fresh database

Build Fails

# Clear everything and reinstall
rm -rf node_modules src/frontend/node_modules
rm package-lock.json src/frontend/package-lock.json
npm install
cd src/frontend && npm install && cd ../..

Updating

From Git

git pull origin main
npm install
cd src/frontend && npm install && cd ../..

Manual Update

1. Backup your database: npm run backup
2. Download new version
3. Copy your tracker.db to new version
4. Run npm install in both root and frontend

Uninstallation

# Save your data first!
cp src/backend/data/tracker.db ~/my-research-backup.db

# Then remove
cd ..
rm -rf project_tracker

Docker (Advanced)

# Coming soon!
# See docs/DOCKER.md for containerized deployment

Next Steps

• Read User Guide to learn features
• Check Customization Guide to personalize
• Set up Backups to protect your data

Need Help?

• Check FAQ
• See Troubleshooting
• Open an Issue
• Start a Discussion

---

Installation Complete! 🎉 Ready to track your research!

This site is open source. Improve this page.