# Thinakkural API — cPanel Deployment Guide

Production URL: `https://news.turnon.lk`

## cPanel requirements

The hosting account must provide Node.js and Passenger/Application Manager support. Use Node.js 18, 20 or 22. Node.js 20 or 22 is preferred.

## 1. Upload

Upload and extract the package outside `public_html`, for example:

```text
/home/CPANEL_USERNAME/thinakkural-api
```

The application root must directly contain `app.js`, `package.json`, `src`, `storage`, `tmp` and `logs`.

## 2. Register the application

In cPanel open **Software → Application Manager** (or **Setup Node.js App**, depending on the host) and use:

```text
Application name: thinakkural-api
Domain / Application URL: news.turnon.lk
Base URL: /
Application path/root: thinakkural-api
Startup file: app.js
Environment: Production
Node.js version: 20 or 22
```

Do not manually add `PORT`; Passenger supplies it.

## 3. Environment variables

Add the values from `.env.cpanel.example` in Application Manager. The most important values are:

```env
NODE_ENV=production
APP_BASE_URL=https://news.turnon.lk
AZURE_TRANSLATOR_KEY=REPLACE_WITH_NEW_TRANSLATOR_KEY
AZURE_TRANSLATOR_ENDPOINT=https://api.cognitive.microsofttranslator.com
AZURE_SPEECH_KEY=REPLACE_WITH_NEW_SPEECH_KEY
AZURE_SPEECH_REGION=southeastasia
AZURE_SPEECH_TTS_ENDPOINT=https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1
CORS_ORIGIN=*
```

`AZURE_TRANSLATOR_REGION` is not needed for the Global Translator resource. `AUDIO_STORAGE_DIR` is also optional; when omitted, the app uses `storage/audio` inside the application root.

If Application Manager does not show environment-variable fields, copy `.env.cpanel.example` to `.env`, replace placeholders, and set permission `600`:

```bash
cd ~/thinakkural-api
cp .env.cpanel.example .env
chmod 600 .env
```

## 4. Install dependencies and permissions

Open cPanel Terminal and run:

```bash
cd ~/thinakkural-api
npm install --omit=dev
mkdir -p storage/audio tmp logs
chmod 755 storage storage/audio tmp logs
npm run check
npm run preflight
```

Some cPanel hosts display the Node virtual-environment command above the application page. Activate that environment before running `npm install` when instructed by cPanel.

## 5. Restart Passenger

Use the Restart button in Application Manager or run:

```bash
touch ~/thinakkural-api/tmp/restart.txt
```

Restart after every code or environment-variable change.

## 6. Verify

```text
https://news.turnon.lk/
https://news.turnon.lk/health
```

Combined request:

```http
POST https://news.turnon.lk/api/v1/translate-and-speech
Content-Type: application/json
```

```json
{
  "text": "இலங்கை இன்று புதிய பொருளாதார திட்டத்தை அறிவித்தது.",
  "gender": "female",
  "format": "mp3"
}
```

The response should contain both `translatedText` and a public URL such as:

```text
https://news.turnon.lk/audio/thinakkural-en-us-....mp3
```

## 7. Troubleshooting

- `503 Service Unavailable`: check the startup file is `app.js`, run `npm install`, then restart Passenger.
- `Cannot find module`: dependencies were not installed in the Node environment selected by cPanel.
- Audio URL returns 404: verify `storage/audio` exists, is writable, and `APP_BASE_URL` is exactly `https://news.turnon.lk`.
- Azure 401/403: regenerate exposed keys and update the environment variables.
- Azure Speech error: confirm region is `southeastasia` and the TTS endpoint is the regional `tts.speech.microsoft.com` endpoint.
- Logs: open `<application-root>/logs/` in File Manager or inspect the error log shown by Application Manager.

## Security before launch

- Regenerate the Translator and Speech keys that were previously exposed.
- Never upload `.env` to Git or share API keys in screenshots/messages.
- Replace `CORS_ORIGIN=*` with the exact frontend domain before public launch.
- Enable AutoSSL for `news.turnon.lk` and use HTTPS in `APP_BASE_URL`.