# Universal cPanel Deployment Guide (VanLocalUK) This guide is written so the same package can be deployed on: - any cPanel account - any main domain - any subdomain - any subfolder path It assumes you are using cPanel `Setup Python App` with Passenger. ## 1. Requirements - Python `3.10` or `3.11` - cPanel with `Setup Python App` - File Manager access - Optional: Terminal access If both `3.10` and `3.11` are available, use `3.11`. If not, `3.10` is fully fine. ## 2. Package contents Your deployment package should include: - `app.py` - `schema.sql` - `passenger_wsgi.py` - `cpanel_initialize.py` - `cpanel_install_wizard.sh` - `README.md` - `CPANEL_INSTALL_WIZARD.md` - `UNIVERSAL_CPANEL_DEPLOYMENT.md` - `PASSENGER_WSGI_REFERENCE.md` - `DEVELOPER_HANDOVER.md` - `vanlocaluk.db` ## 3. Choose your deployment pattern ### Option A: deploy to a subfolder Example: - domain: `example.com` - app URL: `https://example.com/vanlocal/` - application root: `/home//public_html/vanlocal` ### Option B: deploy to the main domain root Example: - domain: `example.com` - app URL: `https://example.com/` - application root: `/home//public_html` If you use the main domain root, make sure it does not already contain another website. ### Option C: deploy to a subdomain Example: - subdomain: `app.example.com` - app URL: `https://app.example.com/` - application root: `/home//app.example.com` ## 4. Recommended file layout Recommended code path: - `/home//public_html/vanlocal` Recommended private data path: - `/home//vanlocaluk_data` Recommended private folders: - `/home//vanlocaluk_data/vanlocaluk.db` - `/home//vanlocaluk_data/private_uploads` - `/home//vanlocaluk_data/backups` This is safer than keeping the database inside `public_html`. ## 5. Upload and extract the package Upload the zip into your chosen application root and extract it there. After extraction, the application root must directly contain: - `app.py` - `schema.sql` - `passenger_wsgi.py` - `cpanel_initialize.py` - `vanlocaluk.db` Do not leave these files inside a nested extracted folder. Important: - cPanel may auto-create or overwrite `passenger_wsgi.py` - If the site returns `500` and `stderr.log` shows recursive `imp.load_source('wsgi', 'passenger_wsgi.py')`, your startup file is wrong - Replace it with the exact file from this package or use `PASSENGER_WSGI_REFERENCE.md` ## 6. Create the Python app in cPanel Open `Setup Python App` and create or edit the application with these values: - Python version: `3.11` or `3.10` - Application root: your chosen app folder - Application URL: `/` or your chosen subfolder - Application startup file: `passenger_wsgi.py` - Application entry point: `application` Example for subfolder deployment: - Application root: `public_html/vanlocal` - Application URL: `vanlocal` The correct `passenger_wsgi.py` must import `wsgi_application` from `app.py` and must not import itself. ## 7. Environment variables Set these exact variables in `Setup Python App`. Recommended production-safe values: ```text VANLOCALUK_VERTICAL=removals VANLOCALUK_TIMEZONE=Europe/London VANLOCALUK_DB=/home//vanlocaluk_data/vanlocaluk.db VANLOCALUK_PRIVATE_UPLOADS=/home//vanlocaluk_data/private_uploads VANLOCALUK_BACKUP_DIR=/home//vanlocaluk_data/backups ``` Optional: ```text VANLOCALUK_ENQUIRY_EMAIL=you@example.com VANLOCALUK_AUTO_BACKUP=1 VANLOCALUK_BACKUP_KEEP=20 ``` Important: - always use full absolute paths starting with `/home//` - do not use `/public_html/...` - do not use relative paths ## 8. Initialize the app You have two ways to initialize the app. ### Method A: with Terminal access Activate the Python app environment shown by cPanel, then run: ```bash cd /home//public_html/vanlocal mkdir -p /home//vanlocaluk_data/private_uploads mkdir -p /home//vanlocaluk_data/backups mkdir -p tmp python3 app.py migrate touch tmp/restart.txt ``` If your database is meant to live outside `public_html`, copy or move the bundled DB: ```bash cp vanlocaluk.db /home//vanlocaluk_data/vanlocaluk.db ``` ### Method B: without Terminal access This package includes `cpanel_initialize.py`. In `Setup Python App`, under `Execute python script`, run: ```text cpanel_initialize.py ``` That script will: - create the private upload folder if needed - create the backup folder if needed - create the app `tmp` folder if needed - run the same initialization logic as `python3 app.py migrate` After that: - click `Restart` in `Setup Python App` ## 9. Restart the app After any file upload, env var change, or initialization: - click `Restart` in `Setup Python App` If Terminal access exists, this also works: ```bash touch /home//public_html/vanlocal/tmp/restart.txt ``` ## 10. First URLs to test ### If deployed in a subfolder like `/vanlocal` - landing page: `https://example.com/vanlocal/` - moving form: `https://example.com/vanlocal/moving` - provider login: `https://example.com/vanlocal/login` - admin login: `https://example.com/vanlocal/1054adminstaffloginportal` ### If deployed at the root domain - landing page: `https://example.com/` - moving form: `https://example.com/moving` - provider login: `https://example.com/login` - admin login: `https://example.com/1054adminstaffloginportal` ## 11. Default clean database logins If you deploy the clean seeded database: - Admin: `admin@vanlocaluk.test` / `admin123` - Provider: `partner@vanlocaluk.test` / `partner123` Change these after the first successful login. ## 12. Safe update process When updating an existing live install: 1. Back up the current database. 2. Upload the new code files. 3. Do not overwrite the live DB unless you intentionally want a clean reset. 4. Run migration or `cpanel_initialize.py`. 5. Restart the app. If you are only updating theme or code: - replace `app.py` - keep your existing live database ## 13. Common 500 error causes If you get `500 Internal Server Error`, check these first: - `passenger_wsgi.py` is the correct file from this package - the app files are not inside a second nested folder after extraction - `VANLOCALUK_DB` uses an absolute path - `VANLOCALUK_PRIVATE_UPLOADS` uses an absolute path - the configured DB file actually exists - the `private_uploads`, `backups`, and `tmp` folders exist - you restarted the app after changing files ## 14. Quick file checklist Application root should contain: - `app.py` - `schema.sql` - `passenger_wsgi.py` - `cpanel_initialize.py` - `tmp/` - `uploads/` Private path should contain: - `vanlocaluk.db` - `private_uploads/` - `backups/` ## 15. Recommended production final values Example final config for a cPanel user named `john` on `example.com/vanlocal`: ```text Application root: public_html/vanlocal Application URL: vanlocal Startup file: passenger_wsgi.py Entry point: application VANLOCALUK_VERTICAL=removals VANLOCALUK_TIMEZONE=Europe/London VANLOCALUK_DB=/home/john/vanlocaluk_data/vanlocaluk.db VANLOCALUK_PRIVATE_UPLOADS=/home/john/vanlocaluk_data/private_uploads VANLOCALUK_BACKUP_DIR=/home/john/vanlocaluk_data/backups VANLOCALUK_ENQUIRY_EMAIL=info@example.com ``` This is the preferred reusable pattern for almost any cPanel domain setup.