xamxam/nginx/TEST_DATABASE_SETUP.md

# Test Database Setup - Post-ERG

Complete guide for deploying and managing the test database on the production server.

---

## 🎯 Quick Deploy

```bash
just test-deploy
```

This automatically:
1. ✅ Creates `/var/www/html/storage/` directory
2. ✅ Uploads `test.db` to the server
3. ✅ Sets correct group ownership (`posterg`)
4. ✅ Sets correct permissions (775 for dir, 660 for file)

---

## 🔧 Prerequisites (One-Time Setup)

### 1. Install PHP SQLite Extension

On the server:
```bash
ssh posterg
sudo bash /tmp/install-php-sqlite.sh
```

Or manually:
```bash
ssh posterg
sudo apt update
sudo apt install php8.4-sqlite3
sudo systemctl restart php8.4-fpm
```

### 2. Verify Installation

```bash
ssh posterg
php -m | grep sqlite3
# Should output: pdo_sqlite, sqlite3
```

---

## 📋 How Database Selection Works

The system automatically detects which database to use:

1. **If `test.db` exists** → Uses test database
2. **Otherwise** → Uses production database (`posterg.db`)

This is configured in `shared/config.php`:

```php
function getDatabasePath() {
    // If test.db exists, use it
    if (file_exists(DB_TEST_PATH)) {
        return DB_TEST_PATH;
    }
    // Otherwise use production database
    return DB_PROD_PATH;
}
```

---

## 🧪 Complete Testing Workflow

### 1. Create Test Data Locally

```bash
# Create empty test database from schema
just init-test-db

# Or create with sample fixtures
just create-fixtures
```

### 2. Deploy Test Database

```bash
just test-deploy
```

### 3. Test the Site

Visit: https://posterg.erg.be/

The site now uses test data! 🎉

### 4. Check What Database is Being Used

```bash
ssh posterg
php -r "require_once '/var/www/html/shared/Database.php'; echo 'Using: ' . Database::getInstance()->getDatabasePath() . PHP_EOL;"
```

Output will be:
- `/var/www/html/storage/test.db` (test mode)
- `/var/www/html/storage/posterg.db` (production mode)

### 5. Switch Back to Production

Simply remove the test database:

```bash
ssh posterg
rm /var/www/html/storage/test.db
```

The site automatically switches to production database.

---

## 🔒 Permissions Explained

### Directory Permissions

```
drwxrwxr-x  theophile posterg  /var/www/html/storage/
```

- **775**: Owner and group can read/write/execute, others can read/execute
- **Group: posterg**: `www-data` is member of this group
- **Writable by group**: SQLite needs to create journal/temp files

### File Permissions

```
-rw-rw----  theophile posterg  test.db
```

- **660**: Owner and group can read/write, others have no access
- **Group: posterg**: `www-data` can read/write the database
- **No public access**: Security - only PHP-FPM can access

---

## 🐛 Troubleshooting

### Site Shows Empty Page or Error

**Check error logs:**
```bash
ssh posterg
tail -f /var/log/nginx/posterg_error.log
```

### "could not find driver"

**SQLite extension not installed:**
```bash
ssh posterg
sudo apt install php8.4-sqlite3
sudo systemctl restart php8.4-fpm
```

### "unable to open database file"

**Wrong permissions:**
```bash
ssh posterg
# Fix group ownership
chgrp posterg /var/www/html/database /var/www/html/storage/test.db

# Fix permissions
chmod 775 /var/www/html/database
chmod 660 /var/www/html/storage/test.db
```

### "SQLSTATE[HY000]: General error: 8 attempt to write a readonly database"

**Directory not writable:**
```bash
ssh posterg
chmod 775 /var/www/html/database
```

### Database Doesn't Update

**Clear SQLite cache:**
```bash
ssh posterg
rm -f /var/www/html/storage/test.db-journal
rm -f /var/www/html/storage/test.db-shm
rm -f /var/www/html/storage/test.db-wal
```

Then redeploy:
```bash
just test-deploy
```

---

## 📊 Check Database Stats

### On Server

```bash
ssh posterg
cd /var/www/html

# Count theses
php -r "require_once 'shared/Database.php'; echo 'Theses: ' . Database::getInstance()->countPublishedTheses() . PHP_EOL;"

# Check database file
ls -lh database/test.db
```

### From Local Machine

```bash
# Show stats from local test database
sqlite3 database/test.db "SELECT COUNT(*) FROM theses;"
sqlite3 database/test.db "SELECT COUNT(*) FROM theses WHERE is_published = 1;"
```

---

## 🔄 Update Test Data

### Update Locally and Redeploy

```bash
# Make changes to local test database
sqlite3 database/test.db
# ... make changes ...

# Deploy updated database
just test-deploy
```

### Update Directly on Server

```bash
ssh posterg
sqlite3 /var/www/html/storage/test.db
# ... make changes ...
```

---

## ⚠️ Important Notes

### Production Safety

The `just deploy` command **excludes all `.db` files** by default:

```bash
# Safe - deploys code only
just deploy
just deploy-public
just deploy-admin

# Safe - deploys schema/docs only
just deploy-database

# Requires explicit command - deploys test.db
just test-deploy
```

This prevents accidentally overwriting production data!

### Never Commit test.db to Git

The `.gitignore` already excludes it:

```
*.db
*.db-journal
```

### Backup Production Database

Before deploying test database, backup production if needed:

```bash
ssh posterg
cp /var/www/html/storage/posterg.db /var/www/html/storage/posterg.db.backup.$(date +%Y%m%d)
```

---

## 🎓 Database File Locations

### Local (Development)

```
/home/theophile/dev/posterg-website/
└── database/
    ├── schema.sql          # Database schema
    ├── test.db            # Test database (gitignored)
    └── fixtures/          # Test data generators
```

### Server (Production)

```
/var/www/html/
└── database/
    ├── posterg.db        # Production database
    └── test.db           # Test database (if deployed)
```

---

## 📚 Related Commands

| Command | Description |
|---------|-------------|
| `just init-test-db` | Create empty test database |
| `just create-fixtures` | Create test database with sample data |
| `just test-deploy` | Deploy test database to server |
| `just stats-public` | Show local database statistics |
| `just query-db` | Open SQLite prompt for local test.db |

---

## ✅ Deployment Checklist

After running `just test-deploy`, verify:

- [ ] Database file exists: `ssh posterg "ls -la /var/www/html/storage/test.db"`
- [ ] Correct permissions: `-rw-rw---- theophile posterg`
- [ ] Directory writable: `drwxrwxr-x theophile posterg`
- [ ] Site loads: Visit https://posterg.erg.be/
- [ ] No errors in logs: `ssh posterg "tail /var/log/nginx/posterg_error.log"`
- [ ] Database accessible: Test with admin panel

---

## 🎉 Success!

When working correctly:

- ✅ Main page shows test data
- ✅ Search works with test data
- ✅ Admin panel loads form
- ✅ No database errors in logs
- ✅ Can create/edit/delete test entries

To switch back to production, just:
```bash
ssh posterg "rm /var/www/html/storage/test.db"
```

Site automatically uses `posterg.db` again! 🚀