# Deploy the vectorizer through cPanel Python App

This deployment is possible only when cPanel shows **Setup Python App** under
Software, or the hosting provider enables **Application Manager** with Python
Passenger. A subdomain by itself does not provide a Python runtime.

The service uses an ASGI-to-WSGI adapter for Passenger. This is a compatibility
deployment for low traffic. Shared-host CPU, RAM and request-time limits may
still make large scanned maps unsuitable.

## Before uploading

1. Create an `A` or `CNAME` DNS record for `vectorizerlan.varclone.com` that
   points to the shared-hosting account.
2. Confirm that `https://vectorizerlan.varclone.com` opens after DNS propagates.
3. In cPanel, confirm **Setup Python App** is available.
4. Ask the host whether Python 3.12, binary pip wheels, 30 MB request bodies and
   requests lasting up to 180 seconds are permitted.

## Create the application

In **Setup Python App**, choose:

- Python version: 3.12 if available
- Application root: `mouza-vectorizer`
- Application URL: `vectorizerlan.varclone.com`
- Application startup file: `app_wsgi.py`
- Application entry point: `application`

CloudLinux generates `passenger_wsgi.py` as a loader. Do not select that same
generated filename as the startup file, or the loader recursively imports
itself. The generated loader must load `app_wsgi.py`.

Do not place this application inside Laravel's public directory. Upload the
contents of `services/mouza-vectorizer` into the application root. Do not upload
the local `.venv`, `.pytest_cache`, `tests` or `tmp` directories.

## Configure environment variables

Use cPanel's Python App environment-variable section:

```dotenv
MOUZA_VECTORIZER_TOKEN=the-same-secret-used-by-laravel
MOUZA_MAX_UPLOAD_BYTES=31457280
MOUZA_ENABLE_DOCS=false
```

Do not expose or commit the token.

## Install dependencies

Copy the virtual-environment activation command displayed by cPanel, open
Terminal, and run it. Then install the requirements from the application root:

```bash
cd ~/mouza-vectorizer
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

If NumPy, OpenCV, PyMuPDF or Shapely fails to install, send the error to the
hosting provider. These packages cannot be replaced by ordinary PHP modules.

Return to **Setup Python App** and click **Restart**.

## Test the service

The public health check should return JSON:

```bash
curl https://vectorizerlan.varclone.com/health
```

The protected endpoint must return HTTP 401 without the shared token:

```bash
curl -i -X POST https://vectorizerlan.varclone.com/v1/vectorize
```

Then update Laravel's production `.env`:

```dotenv
MOUZA_VECTORIZER_URL=https://vectorizerlan.varclone.com
MOUZA_VECTORIZER_TIMEOUT=180
MOUZA_VECTORIZER_TOKEN=the-same-secret-used-by-the-python-app
```

Rebuild Laravel's cached configuration:

```bash
php artisan config:clear
php artisan config:cache
```

Upload a small PNG through the Laravel map editor before trying a large PDF.

## If it fails

- `404`: the subdomain or Application URL is not attached to the Python app.
- `500`: inspect the Python App/Passenger error log; imports or environment
  variables are usually the cause.
- `503 Service authentication is not configured`: add the token in cPanel and
  restart the Python application.
- Process killed, timeout or memory error: ask the provider to raise resource
  limits. If they cannot, move only this service to a VPS/container host.
- No **Setup Python App** or **Application Manager**: this hosting package cannot
  run the service persistently; a cron job is not a valid replacement for this
  HTTP API.