# PROJECT PLANNER - INSTALLATION GUIDE
## For cPanel Shared Hosting Deployment

---

## OVERVIEW

Project Planner is a complete PHP/MySQL web application designed for managing multiple project workspaces with task tracking, workplan imports, and quarterly execution monitoring.

**Features:**
- Multi-user authentication system
- Multiple isolated project workspaces
- CSV workplan import (Excel support requires additional setup)
- Task status tracking
- Progress dashboards
- Filtering and search
- Activity logging
- Responsive design

---

## SYSTEM REQUIREMENTS

**Server Requirements:**
- PHP 7.4 or higher
- MySQL 5.6+ or MariaDB 10.0+
- Apache with mod_rewrite (or Nginx)
- File upload support (minimum 10MB)
- cPanel access (for database setup)

**Recommended PHP Extensions:**
- PDO
- pdo_mysql
- mbstring
- fileinfo
- zip (for future Excel support)

---

## INSTALLATION STEPS

### STEP 1: PREPARE YOUR HOSTING ENVIRONMENT

1. **Login to cPanel**
   - Access your cPanel control panel
   - Navigate to your hosting provider's cPanel URL

2. **Create MySQL Database**
   - Go to "MySQL Databases" in cPanel
   - Create a new database (e.g., `username_planner`)
   - Create a new MySQL user (e.g., `username_planner_user`)
   - Set a strong password and save it
   - Add the user to the database with ALL PRIVILEGES
   - Note down: Database name, Username, Password

### STEP 2: UPLOAD FILES

1. **Access File Manager**
   - In cPanel, open "File Manager"
   - Navigate to `public_html` (or your subdomain folder)

2. **Create Application Folder** (Optional)
   - Create folder: `public_html/project-planner/`
   - Or install directly in `public_html/` for root installation

3. **Upload All Files**
   Upload these files maintaining the directory structure:
   ```
   project-planner/
   ├── css/
   │   └── style.css
   ├── js/
   │   └── project.js
   ├── includes/
   │   ├── header.php
   │   └── spreadsheet-parser.php
   ├── uploads/          (create this folder)
   ├── config.example.php
   ├── database_schema.sql
   ├── login.php
   ├── register.php
   ├── dashboard.php
   ├── create-project.php
   ├── project.php
   ├── add-task.php
   ├── logout.php
   ├── .htaccess
   ├── index.php
   └── INSTALLATION.txt
   ```

4. **Set File Permissions**
   - Set `uploads/` folder to 755 (or 775 if 755 doesn't work)
   - All PHP files: 644
   - All folders: 755

### STEP 3: CONFIGURE DATABASE

1. **Import Database Schema**
   - In cPanel, go to "phpMyAdmin"
   - Select your database (e.g., `username_planner`)
   - Click "Import" tab
   - Choose `database_schema.sql` file
   - Click "Go" to import

2. **Verify Tables Created**
   After import, you should see these tables:
   - users
   - projects
   - tasks
   - milestones
   - deliverables
   - file_uploads
   - activity_log

### STEP 4: CONFIGURE APPLICATION

1. **Create Config File**
   - Rename `config.example.php` to `config.php`
   - Edit `config.php` with your database credentials

2. **Update Database Settings**
   ```php
   define('DB_HOST', 'localhost');           // Usually 'localhost'
   define('DB_NAME', 'username_planner');    // Your database name
   define('DB_USER', 'username_planner_user');// Your database username
   define('DB_PASS', 'your_password_here');  // Your database password
   ```

3. **Update Application URL**
   ```php
   define('BASE_URL', 'https://yourdomain.com/project-planner/');
   // OR for root installation:
   define('BASE_URL', 'https://yourdomain.com/');
   ```
   **IMPORTANT:** URL must end with a forward slash (/)

4. **Set Session Secret**
   ```php
   define('SESSION_SECRET', 'your_random_string_xyz123abc');
   ```
   Generate a random string (20+ characters) for security

5. **Set Timezone**
   ```php
   date_default_timezone_set('America/Toronto'); // Change to your timezone
   ```

6. **Debug Mode (For Initial Setup Only)**
   ```php
   define('DEBUG_MODE', true);  // Set to false after testing
   ```

### STEP 5: VERIFY INSTALLATION

1. **Access Application**
   - Visit: `https://yourdomain.com/project-planner/`
   - You should see the login page

2. **Setup Admin Account (RECOMMENDED METHOD)**
   - Visit: `https://yourdomain.com/project-planner/setup_admin.php`
   - Click "Setup Admin Account" button
   - This creates the admin user with correct password hash
   - Login with: `admin` / `admin123`
   - **IMMEDIATELY delete setup_admin.php after use!**

3. **Alternative: Default Admin Account**
   - If setup script doesn't work, try default login:
   - Username: `admin`
   - Password: `admin123`
   - **If login fails, see LOGIN_FIX_GUIDE.txt**

4. **Change Default Password**
   - After logging in, go to Profile
   - Change password immediately
   - Use a strong, unique password

5. **Test Registration**
   - Click "Register here"
   - Create a new account
   - Verify registration works

6. **Test Login**
   - Login with new account
   - Verify dashboard loads

7. **Create Test Project**
   - Click "New Project"
   - Fill in project details
   - Test CSV upload with sample_workplan.csv
   - Add tasks manually
   - Test status updates

### STEP 6: SECURITY HARDENING

1. **Change Default Admin Password**
   - Login as admin
   - Go to Profile
   - Change password immediately

2. **Disable Debug Mode**
   In `config.php`:
   ```php
   define('DEBUG_MODE', false);
   ```

3. **Secure Uploads Folder**
   Create `.htaccess` in `uploads/` folder:
   ```apache
   # Deny direct access to uploads
   Options -Indexes
   <FilesMatch "\.(php|phtml|php3|php4|php5|phps)$">
     Order Deny,Allow
     Deny from all
   </FilesMatch>
   ```

4. **Set Proper File Permissions**
   - config.php: 640 (or 600)
   - uploads/: 755
   - All other PHP files: 644

5. **Force HTTPS** (If you have SSL certificate)
   In `.htaccess`:
   ```apache
   RewriteEngine On
   RewriteCond %{HTTPS} off
   RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
   ```

---

## POST-INSTALLATION CONFIGURATION

### FILE UPLOAD LIMITS

If you need to increase upload size limits:

1. **Check Current Limits**
   Create a file `info.php`:
   ```php
   <?php phpinfo(); ?>
   ```
   Visit `yoursite.com/info.php` and search for:
   - `upload_max_filesize`
   - `post_max_size`
   - Delete `info.php` after checking!

2. **Increase via .htaccess**
   Add to `.htaccess`:
   ```apache
   php_value upload_max_filesize 20M
   php_value post_max_size 20M
   php_value max_execution_time 300
   php_value max_input_time 300
   ```

3. **Or via php.ini** (if available in cPanel)
   ```ini
   upload_max_filesize = 20M
   post_max_size = 20M
   max_execution_time = 300
   ```

### EMAIL CONFIGURATION (Optional)

To enable email notifications, add SMTP configuration in `config.php`:

```php
// Email Configuration
define('SMTP_HOST', 'smtp.yourdomain.com');
define('SMTP_PORT', 587);
define('SMTP_USERNAME', 'noreply@yourdomain.com');
define('SMTP_PASSWORD', 'your_email_password');
define('SMTP_FROM_EMAIL', 'noreply@yourdomain.com');
define('SMTP_FROM_NAME', 'Project Planner');
```

### EXCEL FILE SUPPORT

The current version supports CSV uploads. For Excel (.xlsx, .xls) support:

1. **Option A: Use Composer** (if available)
   ```bash
   composer require phpoffice/phpspreadsheet
   ```

2. **Option B: Manual Download**
   - Download PhpSpreadsheet library
   - Extract to `includes/vendor/phpspreadsheet/`
   - Update `spreadsheet-parser.php` to include library

3. **Option C: Recommend CSV Conversion**
   - Instruct users to save Excel as CSV before upload
   - This is the simplest approach for shared hosting

---

## TROUBLESHOOTING

### Problem: "Database connection error"
**Solution:**
- Verify database credentials in `config.php`
- Check database user has correct privileges
- Verify database host (usually 'localhost')
- Enable DEBUG_MODE to see detailed error

### Problem: "Invalid username or password" (Admin Login)
**Solution:**
- **BEST FIX:** Use setup_admin.php script
  1. Visit: yoursite.com/project-planner/setup_admin.php
  2. Click "Setup Admin Account"
  3. Login with admin/admin123
  4. Delete setup_admin.php immediately
- See LOGIN_FIX_GUIDE.txt for detailed solutions
- Alternative: Run this SQL query in phpMyAdmin:
  ```sql
  UPDATE users SET password = '$2y$10$rZ5fGwFw5qVYqKxLZz.Zo.vYJ9WzQ6RbqLzV7HvJ4nK.MBVqGCKYy' WHERE username = 'admin';
  ```

### Problem: "File upload failed"
**Solution:**
- **BEST FIX:** Run test_upload.php diagnostic tool
  1. Visit: yoursite.com/project-planner/test_upload.php
  2. Review configuration checks
  3. Test actual upload
  4. Follow suggested fixes
  5. Delete test_upload.php after use
- Check `uploads/` folder exists
- Verify folder permissions (755 or 775)
- Check PHP upload limits
- Verify file size under MAX_FILE_SIZE setting
- See UPLOAD_TROUBLESHOOTING.txt for comprehensive guide

### Problem: "Page not found" / 404 errors
**Solution:**
- Verify BASE_URL in `config.php` is correct
- Ensure BASE_URL ends with trailing slash
- Check `.htaccess` file exists and is readable
- Verify mod_rewrite is enabled

### Problem: "Session errors"
**Solution:**
- Check session folder permissions
- Verify session.save_path is writable
- Clear browser cookies and cache
- Check if register_globals is disabled

### Problem: "Permission denied" errors
**Solution:**
- Set folders to 755
- Set PHP files to 644
- Set config.php to 640 or 600
- Check folder ownership (should match web server user)

---

## BACKUP & MAINTENANCE

### Regular Backups

1. **Database Backup**
   - In cPanel phpMyAdmin
   - Select database > Export > Go
   - Save SQL file regularly

2. **File Backup**
   - Download entire `project-planner/` folder
   - Include `uploads/` folder with user files
   - Store backups offsite

3. **Automated Backups**
   - Use cPanel backup tools
   - Schedule daily/weekly backups
   - Keep multiple backup versions

### Updates & Maintenance

- Monitor activity_log table for unusual activity
- Review file uploads periodically
- Delete old/unused projects if needed
- Update PHP version as recommended
- Check for application updates

---

## SUPPORT & RESOURCES

### Common Tasks

**Change User Password:**
```sql
UPDATE users 
SET password = '$2y$10$...' -- Use PHP password_hash() 
WHERE username = 'username';
```

**Delete User Account:**
```sql
DELETE FROM users WHERE user_id = X;
-- This will cascade delete all projects and tasks
```

**Export Project Data:**
- Use phpMyAdmin to export specific project tasks
- Or create custom export functionality

### File Locations

- Configuration: `/config.php`
- Database Schema: `/database_schema.sql`
- Uploads: `/uploads/`
- Logs: Check `activity_log` table in database

---

## ADVANCED CUSTOMIZATION

### Add Custom Fields

To add custom fields to tasks:

1. Add column to `tasks` table:
```sql
ALTER TABLE tasks ADD COLUMN custom_field VARCHAR(255);
```

2. Update forms in `add-task.php` and `project.php`
3. Update `spreadsheet-parser.php` for imports

### Customize Appearance

- Edit `css/style.css` for colors and styling
- Modify `:root` variables for theme colors
- Update logo in `includes/header.php`

### Add Features

- Email notifications: Integrate PHPMailer
- PDF export: Use TCPDF or FPDF
- Calendar view: Integrate FullCalendar.js
- Gantt charts: Add visualization library

---

## PRODUCTION CHECKLIST

Before going live:

- [ ] Database imported successfully
- [ ] Config file updated with correct credentials
- [ ] BASE_URL set correctly
- [ ] Default admin password changed
- [ ] DEBUG_MODE set to false
- [ ] File permissions set correctly
- [ ] SSL certificate installed (HTTPS)
- [ ] Uploads folder secured
- [ ] Backups configured
- [ ] Email settings configured (if needed)
- [ ] Test account creation
- [ ] Test project creation
- [ ] Test file upload
- [ ] Test task updates
- [ ] Cross-browser testing completed

---

## LICENSE & CREDITS

This application is provided as-is for use in project management.

**Built with:**
- PHP 7.4+
- MySQL/MariaDB
- Vanilla JavaScript
- CSS3

---

## CHANGELOG

**Version 1.0 (Initial Release)**
- User authentication system
- Multi-project workspace support
- CSV workplan import
- Task tracking and status updates
- Progress dashboards
- Activity logging
- Responsive design

---

**Need Help?**

For installation support or custom development:
- Check troubleshooting section above
- Review configuration settings
- Enable DEBUG_MODE for detailed errors
- Consult your hosting provider for server-specific issues

**End of Installation Guide**
