# NexSMS Deployment Guide

This guide covers deploying NexSMS on shared hosting (cPanel) and a VPS/cloud server running PHP 8.2+ and MySQL 8.0+.

---

## Requirements

| Requirement | Version |
|---|---|
| PHP | 8.2 or higher |
| MySQL | 8.0+ (or MariaDB 10.5+) |
| Composer | 2.x |
| Extensions | `pdo_mysql`, `mbstring`, `curl`, `json`, `intl`, `openssl` |

---

## Option A — cPanel Shared Hosting

### 1. Upload Files

Upload the **entire `sms-php/` directory** to your server. It is recommended to place it **outside** of `public_html`:

```
/home/youraccount/
├── nexsms/           ← upload here (app, vendor, etc.)
│   ├── app/
│   ├── public/
│   └── ...
└── public_html/      ← already exists
```

### 2. Point Document Root to `public/`

In cPanel → **Domains** → **Addon Domains** (or subdomain), set the document root to:
```
/home/youraccount/nexsms/public
```

### 3. Create MySQL Database

1. In cPanel → **MySQL Databases**, create a new database and user.
2. Grant **all privileges** to the user on the database.
3. Import the schema:
   - Go to **phpMyAdmin** → select your database → **Import**
   - Upload `schema.sql` first, then `seed.sql`.

### 4. Configure Environment

Copy `env` to `.env` (one level above `public/`):
```bash
cp env .env
```

Edit `.env`:
```ini
CI_ENVIRONMENT = production

app.baseURL = 'https://yourdomain.com/'

database.default.hostname = localhost
database.default.database = yourdb_name
database.default.username = yourdb_user
database.default.password = yourdb_password
database.default.DBDriver = MySQLi
database.default.port     = 3306
database.default.charset  = utf8mb4
database.default.DBCollat = utf8mb4_unicode_ci

# SMS Gateway (optional — remove to use stub)
GATEWAY_PROVIDER = stub
# GATEWAY_PROVIDER = generic_http
# GATEWAY_URL      = https://api.yoursmsgateway.com/send
# GATEWAY_API_KEY  = your_api_key_here
# GATEWAY_SENDER_ID= NexSMS

# JWT Authentication — REQUIRED for API token-based auth
# Generate with: php -r "echo bin2hex(random_bytes(32));"
JWT_SECRET = replace_with_64_char_random_hex_string
JWT_TTL    = 86400

# Session
session.driver     = CodeIgniter\Session\Handlers\FileHandler
session.savePath   = /home/youraccount/nexsms/writable/session
```

### 5. Run Composer (if vendor/ is missing)

SSH into your server and run:
```bash
cd /home/youraccount/nexsms
composer install --no-dev --optimize-autoloader
```

### 6. Set Permissions

```bash
chmod -R 755 /home/youraccount/nexsms
chmod -R 777 /home/youraccount/nexsms/writable
```

### 7. Seed the Default Admin

```bash
php spark db:seed AdminSeeder
```

Default credentials: `admin@bulksms.com` / `Admin@123456`
**Change the password immediately after first login.**

### 8. Set Up the Cron Job

In cPanel → **Cron Jobs**, add:
```
* * * * * cd /home/youraccount/nexsms && php spark sms:worker --batch=500 >> /home/youraccount/nexsms/writable/logs/sms_worker.log 2>&1
```

Or use the provided shell script:
```
* * * * * /home/youraccount/nexsms/queue_worker.sh >> /home/youraccount/nexsms/writable/logs/sms_worker.log 2>&1
```

First make it executable:
```bash
chmod +x /home/youraccount/nexsms/queue_worker.sh
```
Edit `queue_worker.sh` to set `APP_DIR` to your actual path.

---

## Option B — VPS / Cloud Server (Ubuntu/Debian)

### 1. Install Dependencies

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y php8.2 php8.2-cli php8.2-fpm php8.2-mysql php8.2-mbstring \
    php8.2-curl php8.2-intl php8.2-xml php8.2-zip php8.2-bcmath \
    nginx mysql-server composer unzip git
```

### 2. Create Database

```bash
sudo mysql -u root -p
```
```sql
CREATE DATABASE nexsms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'nexsms'@'localhost' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON nexsms.* TO 'nexsms'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### 3. Deploy Application

```bash
sudo mkdir -p /var/www/nexsms
sudo chown -R $USER:www-data /var/www/nexsms

# Upload or clone your files to /var/www/nexsms
cd /var/www/nexsms
composer install --no-dev --optimize-autoloader
cp env .env
# Edit .env as described above
sudo chmod -R 755 /var/www/nexsms
sudo chmod -R 777 /var/www/nexsms/writable
```

### 4. Import Schema & Seed

```bash
mysql -u nexsms -p nexsms < schema.sql
php spark db:seed AdminSeeder
```

### 5. Configure Nginx

Create `/etc/nginx/sites-available/nexsms`:
```nginx
server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/nexsms/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /\. { deny all; }

    access_log /var/log/nginx/nexsms_access.log;
    error_log  /var/log/nginx/nexsms_error.log;
}
```

Enable and test:
```bash
sudo ln -s /etc/nginx/sites-available/nexsms /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

### 6. Set Up Cron

```bash
chmod +x /var/www/nexsms/queue_worker.sh
# Edit queue_worker.sh: set APP_DIR=/var/www/nexsms
crontab -e
```

Add:
```
* * * * * /var/www/nexsms/queue_worker.sh >> /var/log/nexsms_worker.log 2>&1
```

### 7. SSL (Let's Encrypt)

```bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
```

---

## SMS Gateway Configuration

NexSMS ships with a **stub** gateway for testing. To connect a real SMS provider:

1. Set `GATEWAY_PROVIDER = generic_http` in `.env`
2. Set `GATEWAY_URL`, `GATEWAY_API_KEY`, and `GATEWAY_SENDER_ID`

The generic HTTP provider sends a JSON POST:
```json
{
  "to": "+1234567890",
  "from": "NexSMS",
  "message": "Your message here",
  "api_key": "your_api_key"
}
```

For provider-specific formatting, edit `app/Libraries/SmsGateway.php`.

---

## Post-Deployment Checklist

- [ ] `.env` file is configured with correct database credentials
- [ ] `CI_ENVIRONMENT` is set to `production`
- [ ] `JWT_SECRET` is set to a strong random 64-char hex string (generate: `php -r "echo bin2hex(random_bytes(32));"`)
- [ ] `writable/` directory is writable (`chmod 777 writable/`)
- [ ] Default admin password has been changed
- [ ] Cron job is set up and running
- [ ] SMS gateway is configured (or stub is used for testing)
- [ ] SSL certificate is installed

---

## Troubleshooting

| Issue | Solution |
|---|---|
| Blank page | Check `writable/logs/` for errors; ensure `CI_ENVIRONMENT=production` |
| 404 on all pages | Ensure `.htaccess` is in `public/` and `AllowOverride All` is set in Apache |
| Database errors | Verify `.env` credentials and that schema was imported |
| Session errors | Ensure `writable/session/` is writable |
| Cron not running | Check cron logs; verify PHP path with `which php` |