# Installation Guide

Complete guide for installing the Blood Bank Management System SaaS Starter Kit on your server.

---

## Table of Contents

1. [Quick Start](#quick-start)
2. [Prerequisites](#prerequisites)
3. [Installation Methods](#installation-methods)
4. [Post-Installation](#post-installation)
5. [Troubleshooting](#troubleshooting)

---

## Quick Start

**For most users:** Use the web-based installation wizard for a hassle-free setup.

1. Upload files to your server
2. Visit `https://yourdomain.com/install`
3. Follow the 4-step wizard
4. Done! 🎉

---

## Prerequisites

### Server Requirements

- **PHP**: 7.4 or higher (8.0+ recommended)
- **Database**: MySQL 5.7+ or MariaDB 10.2+
- **Web Server**: Apache with mod_rewrite
- **PHP Extensions**: PDO, PDO MySQL, mbstring, JSON, OpenSSL, cURL
- **Storage**: 50MB minimum, 500MB recommended
- **Memory**: 256MB PHP memory limit

**For detailed requirements, see** [server_requirements.md](server_requirements.md)

### Before You Begin

- Database credentials (host, name, username, password)
- FTP/SSH access to your server
- Domain/subdomain pointing to your server
- SSL certificate (recommended)

---

## Installation Methods

### Method 1: Web Installation Wizard (Recommended)

The easiest way to install for most users.

#### Step 1: Upload Files

**Via FTP/cPanel File Manager:**

1. Download the product ZIP file
2. Extract it on your local computer
3. Upload all files to your server's web directory
4. Ensure the `public` folder is the document root

**Important:** On shared hosting (like Hostinger), set document root to `/public_html/public`

#### Step 2: Set Permissions

```bash
chmod -R 755 storage/
chmod -R 755 storage/cache
chmod -R 755 storage/logs
chmod -R 755 storage/uploads
```

Or via cPanel File Manager: Select folders → Permissions → Set to 755

#### Step 3: Create Database

1. Login to cPanel/Hosting Panel
2. Go to MySQL Databases
3. Create a new database (e.g., `blood_bank`)
4. Create a database user
5. Grant all privileges to the user on the database
6. Note down credentials

#### Step 4: Run Installation Wizard

1. Visit `https://yourdomain.com/install` in your browser
2. **Step 1: Requirements Check**
   - Review all requirements
   - Fix any failed checks
   - Click "Continue to Database Setup"

3. **Step 2: Database Configuration**
   - Enter database host (usually `localhost`)
   - Enter database name
   - Enter database username
   - Enter database password
   - Click "Test Connection" to verify
   - Enter your application URL
   - Click "Import Database & Continue"

4. **Step 3: Admin Account**
   - Choose admin username
   - Enter admin email
   - Set a strong password (min 8 characters)
   - Click "Complete Installation"

5. **Step 4: Installation Complete!**
   - Installation successful 🎉
   - Note down your login credentials
   - Click "Go to Admin Login"

#### Step 5: Login

1. Visit `https://yourdomain.com/admin/login`
2. Enter your admin credentials
3. You're in!

---

### Method 2: Manual Installation (Advanced)

For developers who prefer command-line installation.

#### Step 1: Upload Files

```bash
# Via SSH/Terminal
cd /path/to/webroot
unzip bloodbank-v1.0.0.zip
mv Blood-Bank-Management-System/* .
```

#### Step 2: Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit environment file
nano .env
```

Update these values:
```env
APP_URL=https://yourdomain.com
DB_HOST=localhost
DB_DATABASE=blood_bank
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password
LICENSE_KEY=BBMS-XXXX-XXXX-XXXX-XXXX  # Optional
```

#### Step 3: Install Dependencies

```bash
composer install --no-dev --optimize-autoloader
```

#### Step 4: Import Database

```bash
# Create database
mysql -u root -p -e "CREATE DATABASE blood_bank;"

# Import schema
mysql -u root -p blood_bank < storage/database/schema.sql
mysql -u root -p blood_bank < storage/database/enterprise_schema.sql
mysql -u root -p blood_bank < storage/database/api_tokens_schema.sql
```

#### Step 5: Create Admin User

```bash
# Access MySQL
mysql -u root -p blood_bank

# Create admin
INSERT INTO users (username, email, password, role, status, created_at)
VALUES ('admin', 'admin@yourdomain.com', '$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', 'admin', 'active', NOW());
# Password: password (change immediately!)

exit;
```

#### Step 6: Set Permissions

```bash
chmod -R 755 storage/
chown -R www-data:www-data storage/
```

#### Step 7: Create Lock File

```bash
echo "$(date)" > installed.lock
```

---

## Post-Installation

### Essential Configuration

#### 1. Configure Email (SMTP)

Edit `.env`:
```env
MAIL_DRIVER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
```

**Gmail Users:** Use App Password, not regular password.

#### 2. Update License Key (Optional)

If you purchased a license:
```env
LICENSE_KEY=BBMS-XXXX-XXXX-XXXX-XXXX
```

#### 3. Secure Your Installation

1. **Change Default Password** (if manual install)
   - Login → Settings → Change Password

2. **Enable HTTPS** (if not already)
   - Install SSL certificate
   - Uncomment HTTPS redirect in `/public/.htaccess`

3. **Restrict File Permissions**
   ```bash
   chmod 444 .env
   chmod 444 installed.lock
   ```

#### 4. Configure Cron Jobs (Optional)

Add to crontab for automated maintenance:
```bash
# Clean old audit logs (daily at 2 AM)
0 2 * * * cd /path/to/app && php cli.php audit:prune

# Clean expired cache (hourly)
0 * * * * cd /path/to/app && php cli.php cache:clean

# Clean rate limits (every 6 hours)
0 */6 * * * cd /path/to/app && php cli.php rate-limit:clean
```

---

### Optional: Demo Data

For testing purposes, populate with sample data:

```bash
php cli.php seed:demo
```

This creates:
- 30 sample donors (all blood types)
- 15 blood requests
- 5 messages
- Demo admin (email: `demo@bloodbank.com`, password: `demo123`)

To re-seed:
```bash
php cli.php seed:demo --force
```

---

## Troubleshooting

### Installation Wizard Not Loading

**Problem:** Blank page or 404 error at `/install`

**Solutions:**
1. Check document root points to `/public` folder
2. Verify `.htaccess` exists in `/public`
3. Ensure mod_rewrite is enabled
4. Check file permissions (755 for directories)

On Hostinger, change document root:
`hPanel → Advanced → Domain Settings → Document Root → /public_html/public`

### Database Connection Failed

**Problem:** "Connection refused" or "Access denied"

**Solutions:**
1. Verify database credentials in wizard form
2. Check database exists: `SHOW DATABASES;`
3. Ensure user has privileges: `GRANT ALL ON db.* TO 'user'@'localhost';`
4. Try `127.0.0.1` instead of `localhost` as host
5. Check if MySQL service is running

### White Screen After Installation

**Problem:** Blank page after clicking "Complete Installation"

**Solutions:**
1. Check PHP error logs
2. Verify storage folders are writable
3. Ensure all database tables imported successfully
4. Clear browser cache
5. Check `.env` file was created

### Permission Denied Errors

**Problem:** Cannot write to storage directories

**Solutions:**
```bash
chmod -R 755 storage/
chown -R www-data:www-data storage/

# Or for shared hosting
chmod -R 777 storage/  # Less secure but may be necessary
```

### "Class Not Found" Errors

**Problem:** PHP Fatal error: Class 'X' not found

**Solutions:**
1. Run `composer install`
2. Verify `vendor/` directory exists
3. Check `composer.json` is present
4. Ensure PHP version >= 7.4

### 500 Internal Server Error

**Problem:** Server error 500

**Solutions:**
1. Check Apache/PHP error logs
2. Verify `.htaccess` syntax is correct
3. Ensure PHP extensions are enabled
4. Check file permissions
5. Enable debug mode temporarily:
   ```env
   APP_DEBUG=true
   ```
   (Disable after troubleshooting!)

---

## Verification

Run the deployment check script to verify installation:

```bash
php deployment_check.php
```

This checks:
- ✓ Environment file exists
- ✓ Database connection
- ✓ Required directories writable
- ✓ PHP extensions loaded
- ✓ .htaccess security

All checks should pass.

---

## Next Steps

After installation:

1. **Login to Admin Panel**: `https://yourdomain.com/admin/login`
2. **Change Password**: Update default/setup password
3. **Configure Email**: Set up SMTP for notifications
4. **Add Donors**: Start adding blood donors
5. **Test Features**: Create a blood request, send a message
6. **Review Settings**: Check timezone, app name, etc.
7. **Backup**: Set up regular database backups

---

## Getting Help

- **Documentation**: `/docs` folder
- **Server Requirements**: See `server_requirements.md`
- **API Documentation**: See `api_documentation.md`
- **Customization**: See `customization_guide.md`
- **Deployment**: See `deployment_guide.md`

---

## Security Best Practices

1. **Never commit `.env`** to version control
2. **Use strong passwords** (min 12 characters)
3. **Enable HTTPS** (always use SSL)
4. **Keep PHP updated** (security patches)
5. **Regular backups** (database + files)
6. **Restrict admin access** (IP whitelist if possible)
7. **Monitor logs** (check for suspicious activity)

---

**Congratulations! Your Blood Bank Management System is now installed and ready to use!** 🎉

For customization and development, see the [Customization Guide](customization_guide.md).