# cPanel Setup Tutorial

This guide is written for normal shared cPanel hosting without root access.

## What this app is

This portal is a Flask WSGI app built to fit the Python hosting features cPanel providers usually expose:

- `Application Manager`
- `Setup Python App`
- Passenger / CloudLinux Python app support

That is why this build uses Flask WSGI instead of a FastAPI-first ASGI stack.

## Good News First

You do not need root access for this scaffold.

If your host gives you:

- cPanel Python app support
- a home directory
- a domain or subdomain
- terminal access or SSH

then this portal can be deployed.

## Official cPanel References

- [How do I set up a Python web application?](https://support.cpanel.net/hc/en-us/articles/360049921014-How-do-I-set-up-a-Python-web-application)
- [How to Install a Python WSGI Application](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-a-python-wsgi-application/)
- [Using Passenger Applications](https://docs.cpanel.net/knowledge-base/web-services/using-passenger-applications/)
- [How to register an application with Python Selector](https://support.cpanel.net/hc/en-us/articles/360057849753-How-to-register-an-application-with-Python-Selector)

## Example Final Layout

Your final app path will usually look like:

```text
/home/yourcpaneluser/hostable_portal
```

And your URL may look like:

```text
https://portal.yourdomain.com
```

## Important Files

- `app.py`
- `passenger_wsgi.py`
- `requirements.txt`
- `.env`
- `init_db.py`

## Step 1. Upload the Portal

Upload the full [hostable_portal](C:/--QT%20HOSTABLE--/hostable_portal) folder into your cPanel account.

Recommended location:

```text
/home/yourcpaneluser/hostable_portal
```

## Step 2. Open Terminal

In cPanel:

1. Open `Terminal` if your host provides it
2. Or connect over SSH if your host gives SSH access

Then move into the app folder:

```bash
cd ~/hostable_portal
```

## Step 3. Create the Virtual Environment

Run:

```bash
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```

If your host uses a different Python binary, replace `python3` with the version they provide.

## Step 4. Create the Environment File

Create `.env` in the app folder.

Example:

```env
SECRET_KEY=put-a-long-random-secret-here
DATABASE_URL=sqlite:///portal.db
SESSION_COOKIE_SECURE=true
REMEMBER_COOKIE_SECURE=true
HOSTABLE_APP_NAME=SPANDAMAN Hostable Portal
```

For your first shared-host deployment, SQLite is the easiest choice.

## Step 5. Create the First Admin

Still inside the app folder:

```bash
source venv/bin/activate
python init_db.py --admin-username admin --admin-email you@example.com --admin-password "ChangeThisNow123!"
```

That creates:

- the database
- the first admin account

## Step 6. Create the Python App in cPanel

### Option A. Application Manager

If your host exposes `Application Manager`:

1. Open `Application Manager`
2. Click `Create Application`
3. Choose the domain or subdomain
4. Set application root to your portal folder
5. Set the startup file to `passenger_wsgi.py`
6. If an entry point field appears, set it to `application`

### Option B. Setup Python App / CloudLinux Python App

If your host uses CloudLinux:

1. Open `Setup Python App`
2. Create the app
3. Choose the Python version your host provides
4. Point it at the same folder
5. Use `passenger_wsgi.py` as startup file
6. Use `application` as entry point if requested

## Step 7. Restart the App

After code changes, restart Passenger:

```bash
mkdir -p tmp
touch tmp/restart.txt
```

## Step 8. Sign In

Open your portal URL and go to:

```text
/login
```

Sign in with the admin account created in Step 5.

## Step 9. Immediate Security Tasks

Do these right away:

- change the bootstrap admin password if needed
- create a second admin or operator account
- verify HTTPS is enabled
- keep `.env` private
- back up `portal.db`

## What This Build Already Includes

- password hashing with Werkzeug
- secure cookie flags
- CSRF protection on forms
- role checks
- repeated-login lockout
- audit log storage

## Common Problems

### The Python app feature is missing

Your host may:

- only expose `Application Manager`
- only expose `Setup Python App`
- not support Python apps on your plan

### The app does not start

Check:

1. the app root is correct
2. `passenger_wsgi.py` is the startup file
3. dependencies were installed inside the app virtualenv
4. `.env` exists
5. you restarted the app

### Login page opens but styles do not load

Check:

- static files uploaded correctly
- app root is not pointing one folder too high or too low

### You get import errors

Usually this means:

- requirements were not installed
- the Python app is using the wrong interpreter
- the app root is wrong

## Beginner Deployment Order

If you want the shortest working order:

1. upload files
2. create virtualenv
3. install requirements
4. create `.env`
5. run `init_db.py`
6. register app in cPanel
7. restart app
8. open `/login`

## Next Phase After This

Once login is live, the next build phase should add:

- password reset
- 2FA
- invite-based user management
- source credential vaulting
- import jobs
- hosted playlist browsing and repair tools