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

just test-deploy

This automatically:

1. ✅ Creates /var/www/html/database/ 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:

ssh posterg
sudo bash /tmp/install-php-sqlite.sh

Or manually:

ssh posterg
sudo apt update
sudo apt install php8.4-sqlite3
sudo systemctl restart php8.4-fpm

2. Verify Installation

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:

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

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

# Or create with sample fixtures
just create-fixtures

2. Deploy Test Database

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

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/database/test.db (test mode)
• /var/www/html/database/posterg.db (production mode)

5. Switch Back to Production

Simply remove the test database:

ssh posterg
rm /var/www/html/database/test.db

The site automatically switches to production database.

---

🔒 Permissions Explained

Directory Permissions

drwxrwxr-x  theophile posterg  /var/www/html/database/

• 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:

ssh posterg
tail -f /var/log/nginx/posterg_error.log

"could not find driver"

SQLite extension not installed:

ssh posterg
sudo apt install php8.4-sqlite3
sudo systemctl restart php8.4-fpm

"unable to open database file"

Wrong permissions:

ssh posterg
# Fix group ownership
chgrp posterg /var/www/html/database /var/www/html/database/test.db

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

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

Directory not writable:

ssh posterg
chmod 775 /var/www/html/database

Database Doesn't Update

Clear SQLite cache:

ssh posterg
rm -f /var/www/html/database/test.db-journal
rm -f /var/www/html/database/test.db-shm
rm -f /var/www/html/database/test.db-wal

Then redeploy:

just test-deploy

---

📊 Check Database Stats

On Server

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

# 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

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

# Deploy updated database
just test-deploy

Update Directly on Server

ssh posterg
sqlite3 /var/www/html/database/test.db
# ... make changes ...

---

⚠️ Important Notes

Production Safety

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

# 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:

ssh posterg
cp /var/www/html/database/posterg.db /var/www/html/database/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/database/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:

ssh posterg "rm /var/www/html/database/test.db"

Site automatically uses posterg.db again! 🚀