# Step-by-Step cPanel Deployment Guide (with MySQL)

This guide walks you through deploying the **Gakuuru** web application (Django backend & React frontend) on a standard cPanel hosting environment using a MySQL/MariaDB database.

---

## 1. Hosting Architecture Overview
For the best performance and security, we recommend the following folder structure and domain configuration:
- **Frontend (React)**: Deployed inside the public HTML directory (`/public_html`) of your main domain (e.g. `gakuuru.com`).
- **Backend (Django)**: Uploaded to a folder *outside* the public directory (e.g., `/home/username/gakuuru-backend`) and served on a subdomain (e.g., `api.gakuuru.com`) using cPanel's **Setup Python App** tool.

---

## 2. Step 1: Create a MySQL Database in cPanel
1. Log in to your cPanel dashboard.
2. Search for and open **MySQL Database Wizard**.
3. **Step 1: Create A Database**: Enter a name for your database (e.g., `username_gakuurudb`) and click **Next Step**.
4. **Step 2: Create Database Users**: Enter a username (e.g., `username_dbuser`) and generate a strong password. **Write down these credentials.** Click **Create User**.
5. **Step 3: Add User to the Database**: Tick the **ALL PRIVILEGES** checkbox and click **Make Changes**.

---

## 3. Step 2: Set Up the Backend (Django) on cPanel
1. Compress your `backend` folder locally as a `.zip` file (excluding database files like `db.sqlite3` and folders like `.venv` or `__pycache__`).
2. Upload the `.zip` file to your home directory `/home/username` in cPanel **File Manager** and extract it into a folder named `/home/username/gakuuru-backend`.
3. In cPanel, search for **Setup Python App** (under Software section).
4. Click **Create Application** and fill out the details:
   - **Python version**: Select version `3.10` or higher.
   - **Application root**: Enter `gakuuru-backend` (relative to your home directory).
   - **Application URL**: Select the domain/subdomain you wish to use (e.g., `api.yourdomain.com`).
   - **Application startup file**: Enter `passenger_wsgi.py`.
   - **Application Entry point**: Leave blank (defaults to `application`).
5. Click **Create** at the top right.

---

## 4. Step 3: Configure Environment Variables
Inside `/home/username/gakuuru-backend/`, create a file named `.env` using cPanel File Manager and enter your production credentials:
```env
DB_ENGINE=django.db.backends.mysql
DB_NAME=username_gakuurudb
DB_USER=username_dbuser
DB_PASSWORD=your_strong_password
DB_HOST=127.0.0.1
DB_PORT=3306

DEBUG=False
SECRET_KEY=generate-a-long-random-string-here
ALLOWED_HOSTS=api.yourdomain.com
CORS_ALLOWED_ORIGINS=https://yourdomain.com
```
*Note: Replace `yourdomain.com` with your actual domain name and `api.yourdomain.com` with your subdomain.*

---

## 5. Step 4: Install Dependencies & Run Database Migrations
1. In the **Setup Python App** page, click on your app to edit it.
2. At the top of the page, copy the command to enter the virtual environment (it looks like `source /home/username/nodevenv/gakuuru-backend/.../bin/activate`).
3. Connect to your server via SSH (or use the **Terminal** tool in cPanel) and paste that command.
4. Once inside the virtual environment, run:
   ```bash
   pip install --upgrade pip
   pip install -r requirements.txt
   ```
   *Note: If `mysqlclient` fails to compile because the host lacks MariaDB developer headers, install `pymysql` instead: `pip install pymysql` (Django settings are pre-configured to fall back to `pymysql` if `mysqlclient` is absent).*
5. Run migrations to create the database tables in MySQL:
   ```bash
   python manage.py migrate
   ```
6. Collect static files into the `staticfiles` folder:
   ```bash
   python manage.py collectstatic --no-input
   ```

---

## 6. Step 5: Build and Deploy the Frontend (React)
1. In your local development machine, navigate to the `frontend/` directory.
2. Create or edit a `.env.production` file inside the `frontend/` folder:
   ```env
   VITE_API_URL=https://api.yourdomain.com
   ```
   *(Ensure the URL matches your backend subdomain configured in Step 2).*
3. Run the production build command locally:
   ```bash
   npm run build
   ```
   This will compile the React code and assets into a folder named `dist/`.
4. Compress the contents of `dist/` as a `.zip` file.
5. In cPanel **File Manager**, navigate to the `/public_html` directory of your main website.
6. Upload the zip file and extract the contents directly into `/public_html`. You should see `index.html`, `assets/`, and other files in the root.

---

## 7. Step 6: Configure Client-Side Routing (.htaccess)
To ensure React Router can handle page reloads (avoiding 404 errors when visiting pages directly), create or edit the `.htaccess` file in `/public_html` and append the following configuration:
```apache
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteCond %{REQUEST_FILENAME} !-l
  RewriteRule . /index.html [L]
</IfModule>
```

---

## 8. Deployment Completed!
Visit your main domain (`https://yourdomain.com`) in your browser to verify that the frontend loads, connects successfully to the cPanel backend API, and accesses the MySQL database.