# Deployment Guide

## Development Setup

```bash
npm install
npm start
```

The primary local server runs on port 8080 by default.

If you specifically need to exercise the PHP fallback locally, use:

```bash
php -S localhost:8080
```

That mode is only for testing `api.php` style hosting behavior.

## Production Deployment

### Environment Configuration

1. Copy `.env.example` to `.env` in your production environment
2. Update all configuration values, especially:
   - `NODE_ENV=production`
   - `DEFAULT_ADMIN_EMAIL` - Change from default
   - `DEFAULT_ADMIN_PASSWORD` - Change from default to a strong password
   - `PORT` - Adjust as needed (typically 3000 or behind reverse proxy)

### Using Process Manager

For production, use a process manager like PM2:

```bash
npm install -g pm2
pm2 start server.js --name "cdeis-minerals"
pm2 save
```

### Reverse Proxy Setup

If using Nginx as a reverse proxy:

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

### Apache/cPanel Hosting

Use the PHP API mode for cPanel hosting:

Canonical production host for this deployment: `https://www.abeqoqibenhlelo.com`

#### Standard cPanel PHP Hosting

The hosted API routes are PHP-first:

- `/api/*` routes to `api.php`
- `/knowledge-api/*` routes to `knowledge-api.php`

1. Upload the project into `public_html` (or your target web root).
2. Ensure PHP 8.1+ is selected in cPanel.
3. Keep `.htaccess` in the project root so PHP receives API traffic.
   - This is required for login, CDEISLAB, admin, commerce, and knowledge requests.
   - The PHP API supports read-only `/api/wallet-balance` requests for registered wallets when no private key is supplied.
4. Set environment values in cPanel:
  - `DATABASE_PATH=/home/CPANEL_USERNAME/cdeis-data/cdeis.sqlite`
  - `DEFAULT_ADMIN_EMAIL=<your-admin-email>`
  - `DEFAULT_ADMIN_PASSWORD=<strong-password>`
  - `ADMIN_PASSWORD_SALT=<the existing database's password salt>` — preserve this exact value when moving accounts. Changing it invalidates their existing passwords. Choose a new salt only for a new, empty installation.
  - `PHP_SESSION_COOKIE_NAME=cdeis_php_session`
5. Do not configure a separate backend app for `/api` or `/knowledge-api` on the same live site.

Create the writable DB folder:

```bash
mkdir -p /home/CPANEL_USERNAME/cdeis-data
```

### Database

- SQLite is suitable for development and small deployments
- Set `DATABASE_PATH` to a writable absolute path on cPanel (recommended outside `public_html`)
- Example: `/home/CPANEL_USERNAME/cdeis-data/cdeis.sqlite`
- Ensure the folder exists and is writable by PHP
- For production with very high concurrency, plan a separate database migration project:

```bash
# Example only: this codebase is currently configured for SQLite.
```

### Security Checklist

- [ ] Change default admin credentials
- [ ] Update all environment variables
- [ ] Enable HTTPS/SSL
- [ ] Use PHP 8.1+ with `pdo_sqlite` enabled
- [ ] Configure firewall rules
- [ ] Set up regular database backups
- [ ] Enable logging and monitoring
- [ ] Review CORS configuration if needed

### Monitoring

Monitor application logs:

```bash
tail -f application.log
```

Check process status:

```bash
pm2 status
pm2 logs cdeis-minerals
```

### Database Backup

Regular SQLite database backups:

```bash
# Manual backup
cp cdeis.sqlite cdeis.sqlite.backup.$(date +%Y%m%d)

# Automated backup (cron job)
0 2 * * * cp /path/to/cdeis.sqlite /backup/cdeis.sqlite.$(date +\%Y\%m\%d)
```

### cPanel SQLite Setup (Required)

1. Create a data folder in your account home (not in public web root), for example:

```bash
mkdir -p /home/CPANEL_USERNAME/cdeis-data
```

2. In cPanel environment variables, set:

```env
DATABASE_PATH=/home/CPANEL_USERNAME/cdeis-data/cdeis.sqlite
DEFAULT_ADMIN_EMAIL=admin@example.com
DEFAULT_ADMIN_PASSWORD=ChangeMeNow
ADMIN_PASSWORD_SALT=ChangeThisSalt
```

3. Load the site once; the app auto-creates tables in SQLite.
4. If using restrictive permissions, ensure webserver user can write to the DB folder.

If the app says database missing, it is usually one of these:
- `DATABASE_PATH` points to a non-writable folder.
- PHP process cannot create files in the target directory.

## Troubleshooting

### Port Already in Use

```bash
# Find process using port 8080
lsof -i :8080
# Kill the process
kill -9 <PID>
```

### Database Lock Issues

If experiencing database lock issues:

```bash
# Ensure no other processes are using the database
# Restart the server
pm2 restart cdeis-minerals
```

### Session Issues

If users are randomly logged out:

- Check `SESSION_TTL_HOURS` setting
- Verify database integrity
- Check server logs for errors
- Confirm the site is consistently using the PHP API routes:
  - `/api/*` via `api.php`
  - `/knowledge-api/*` via `knowledge-api.php`
- Confirm `SESSION_COOKIE_NAME` and `PHP_SESSION_COOKIE_NAME` are not colliding