# Namecheap Shared Hosting Deployment

This project is prepared for Namecheap `cPanel > Setup Python App` shared hosting deployments.

## Official Namecheap references

- Python apps on shared hosting:
  `https://www.namecheap.com/support/knowledgebase/article.aspx/10048/2182/how-to-work-with-python-app/`
- Shared hosting resource limits:
  `https://www.namecheap.com/support/knowledgebase/article.aspx/1127/103/a-handy-guide-to-resource-limits-or-what-is-lve/`
- Inode limits:
  `https://www.namecheap.com/support/knowledgebase/article.aspx/9331/29/how-to-check-the-number-of-inodes-in-your-hosting-account/`
- Hosting AUP and disk usage limits:
  `https://www.namecheap.com/legal/hosting/aup/`

## Recommended layout

```text
/home/USERNAME/
|-- khf_smp/                    # application root created in Setup Python App
|   |-- app/
|   |-- database/
|   |-- scripts/
|   |-- passenger_wsgi.py
|   |-- wsgi.py
|   `-- .env
|-- khf_smp_data/               # writable data outside public_html
|   |-- uploads/
|   |-- tmp/
|   `-- logs/
`-- public_html/                # do not store ticket attachments here
```

## Recommended Python App values

In `cPanel > Setup Python App > Create Application` use:

- Python version: `3.11` or `3.12`
- Application root: `khf_smp`
- Application URL: `/` or your preferred subpath
- Application startup file: `passenger_wsgi.py`
- Application entry point: `application`

`passenger_wsgi.py` in this project already defaults to `FLASK_CONFIG=namecheap`.

## Required environment values

Use `.env.namecheap.example` as the base, or add the same variables from the Python App environment-variables screen:

```env
FLASK_CONFIG=namecheap
SECRET_KEY=replace-with-a-strong-secret
DATABASE_URL=mysql+pymysql://DB_USER:DB_PASSWORD@localhost/DB_NAME

INSTANCE_PATH=/home/USERNAME/khf_smp/instance
DATA_ROOT=/home/USERNAME/khf_smp_data
UPLOAD_ROOT=/home/USERNAME/khf_smp_data/uploads
FILE_STORAGE_PATH=/home/USERNAME/khf_smp_data/uploads
TEMP_UPLOAD_DIR=/home/USERNAME/khf_smp_data/tmp
LOG_DIR=/home/USERNAME/khf_smp_data/logs

DB_POOL_CLASS=null
DB_POOL_SIZE=2
DB_MAX_OVERFLOW=1
DB_POOL_TIMEOUT=30
DB_POOL_RECYCLE=280
TRUST_PROXY_FIX=1

MAX_UPLOAD_SIZE_MB=32
MAX_UPLOAD_FILES_PER_REQUEST=10
MAX_UPLOAD_BATCH_SIZE_MB=96
MAX_UPLOAD_FILENAME_LENGTH=180
ALLOWED_UPLOAD_EXTENSIONS=log,txt,zip,pdf,png,jpg,jpeg,doc,docx,xls,xlsx,csv
BLOCKED_UPLOAD_EXTENSIONS=exe,dll,so,bin,msi,bat,cmd,com,ps1,sh,php,php3,php4,php5,phtml,phar,pl,py,cgi,jar,war,htaccess,env,ini
STRICT_SHARED_UPLOAD_POLICY=1
TELEGRAM_NOTIFICATIONS_ENABLED=1
TELEGRAM_BOT_TOKEN=replace-with-bot-token
TELEGRAM_BOT_USERNAME=your_bot_username
TELEGRAM_WEBHOOK_SECRET=replace-with-random-secret
TELEGRAM_LINK_TTL_MINUTES=30
```

Important:

- On Namecheap, environment variables added from `Setup Python App` should be treated as the source of truth.
- In the `namecheap` profile, upload storage path, upload extensions, and upload size are locked to hosting config values, so old database settings do not override them.
- If you use Telegram delivery, keep the bot token in the Python App environment variables rather than in tracked files.

## Upload policy used by this project on Namecheap

The `namecheap` hosting profile now applies a stricter upload policy:

- single file limit: `32 MB`
- max files per request: `10`
- max total batch size per request: `96 MB`
- allowed types: office files, logs, text, images, zip, csv/xls/xlsx
- blocked types: executables, scripts, compiled binaries, shell files, `.env`, `.ini`, `.htaccess`
- uploads without an extension are rejected
- file names longer than `180` characters are rejected

This aligns better with shared-hosting usage and reduces the chance of abuse or false-positive malware scans.

## Why these limits matter on Namecheap

Namecheap documents several important shared-hosting limits:

- Python apps on shared hosting run through LiteSpeed + Passenger and must expose a WSGI callable named `application`.
- Shared hosting accounts have CloudLinux resource limits.
- Shared hosting inode limits are typically `300,000` on Stellar/Stellar Plus and `600,000` on Stellar Business.
- Once an account exceeds `200,000` inodes, automatic backups can be excluded.
- Namecheap does not allow shared hosting to be used as general file storage.
- Their AUP limits some content classes such as multimedia files, archive/disk images, database dumps, and executable files to `10 GB` each on shared hosting.

Because of that, ticket attachments should stay business-oriented, moderate in size, and outside `public_html`.

## First deployment steps

1. In Namecheap cPanel, create the Python app.
2. Upload the project files into the application root, usually `/home/USERNAME/khf_smp/`.
3. Upload or create the `.env` file in the application root.
4. Create writable directories:

```bash
mkdir -p ~/khf_smp_data/uploads
mkdir -p ~/khf_smp_data/tmp
mkdir -p ~/khf_smp_data/logs
mkdir -p ~/khf_smp/instance
```

5. Create the MySQL database and user in cPanel.
6. Activate the Python virtual environment using the exact command shown by `Setup Python App`.
7. Install dependencies:

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

8. Import the schema:

If SSH MySQL access is available:

```bash
mysql -u DB_USER -p -h localhost DB_NAME < database/mysql_schema.sql
```

If SSH MySQL import is not available:

- open `phpMyAdmin`
- select the target database
- import `database/mysql_schema.sql`

9. Seed defaults:

```bash
python scripts/seed_data.py
```

10. If you are upgrading an existing database, apply the user security update:

```bash
python scripts/apply_user_security_update.py
```

11. Run the Namecheap preflight:

```bash
python scripts/namecheap_preflight.py
```

12. In `Setup Python App`, click `Restart`.

## Optional troubleshooting

If Passenger returns a generic server error and you need a temporary detailed traceback, Namecheap documents this directive:

```apache
PassengerFriendlyErrorPages on
```

Add it only temporarily in `.htaccess`, restart the Python app, inspect the traceback, then remove it again.

## Operational notes

- Keep ticket files under `khf_smp_data/uploads`, not under `public_html`.
- Do not upload account backups, DB dumps, videos, or large archives into the ticketing system.
- Monitor inode growth in cPanel if users attach many small files.
- Application logs already rotate to stay small enough for shared hosting.
- For Telegram delivery, each user can link Telegram from `Profile`:
  1. save their mobile number in KHF SMP
  2. click `Connect Telegram`
  3. open the bot and press `Start`
  4. share the same mobile number from Telegram
  5. the platform saves the `telegram_chat_id` automatically
- After deployment, set the Telegram webhook:

```bash
flask telegram-set-webhook --base-url https://your-domain.example
```