# Putting the system online (LankaHost cPanel)

| | |
|---|---|
| Live site | https://appletek.lk |
| cPanel user | `mytechno` |
| Server folder (the whole project) | `/home/mytechno/appletek-app` |
| Document root of appletek.lk | `/home/mytechno/appletek-app/public` |
| PHP | 8.2 |

Only the `public` folder can be opened from the web. Everything else — `.env` (passwords), `storage` (customer photos and PDFs), the code — stays outside it, safe.

The server has **no Node.js**, so CSS and JavaScript are built on your PC. You always upload one file: `release.zip`.

---

## Part A — First upload (do this once)

### A1. Make release.zip on your PC

1. Open the project folder on your PC.
2. Double-click **`build-release.bat`**. It takes a few minutes.
3. At the end it says **"DONE: release.zip is ready"**. If it says **BUILD FAILED**, read the message above it.

`release.zip` has everything the server needs (including `vendor` and the built CSS/JS) and nothing private: no `.env`, no tests, no logs, no customer photos.

### A2. Set PHP to 8.2

1. cPanel → **Select PHP Version** (or **MultiPHP Manager**).
2. Choose **PHP 8.2** for appletek.lk.
3. Make sure these extensions are ticked: **pdo_mysql, mbstring, gd, fileinfo, dom, xml, openssl, curl, zip, intl** (gd is needed for photos, QR codes and PDFs).

### A3. Create the database

1. cPanel → **MySQL Databases**.
2. Create a database, for example `appletek`. cPanel names it **`mytechno_appletek`**.
3. Create a user, for example `appletek`, with a strong password. cPanel names it **`mytechno_appletek`**. Write the password down.
4. **Add the user to the database** and tick **ALL PRIVILEGES**.

### A4. Create the email account

1. cPanel → **Email Accounts** → **Create**: `repairs@appletek.lk`, with a strong password. Write it down.
2. Click **Connect Devices** next to it. Check the **Outgoing Server** (normally `mail.appletek.lk`) and the **SMTP port** (465).

### A5. Point the domain to the public folder

1. cPanel → **Domains**.
2. For **appletek.lk**, set the **Document Root** to: `/home/mytechno/appletek-app/public`

> If cPanel does not let you change it (this happens when appletek.lk is the main domain of the account and uses `public_html`), open a ticket with LankaHost support and ask them to set the document root of appletek.lk to `/home/mytechno/appletek-app/public`. Do **not** copy the project into `public_html`.

### A6. Upload and extract

1. cPanel → **File Manager**. Create the folder `/home/mytechno/appletek-app` (next to `public_html`, not inside it).
2. Open it, click **Upload**, and upload `release.zip`.
3. Right-click `release.zip` → **Extract** → into `/home/mytechno/appletek-app`.
4. Delete `release.zip` from the server.
5. Check that you can see `app`, `public`, `storage`, `vendor` and `artisan` directly inside `/home/mytechno/appletek-app`.

### A7. Create the .env file (settings and passwords)

1. In File Manager, click **Settings** (top right) and tick **Show Hidden Files**.
2. In `/home/mytechno/appletek-app`, right-click **`.env.production.example`** → **Copy** → name it **`.env`**.
3. Right-click `.env` → **Edit**. Fill in:
   - `DB_PASSWORD=` the database password from A3
   - `MAIL_PASSWORD=` the email password from A4 (keep the quotes)
   - `ADMIN_EMAIL=` your email, for the first admin login
   - `ADMIN_PASSWORD=` a strong password, at least 8 characters
4. Check `DB_DATABASE` and `DB_USERNAME` match A3, and `APP_URL=https://appletek.lk`.
5. **Save**.

### A8. Install (Terminal)

cPanel → **Terminal** (if you don't see it, ask LankaHost to enable SSH/Terminal). Type these one by one:

```
cd ~/appletek-app
php -v
```

`php -v` must say **PHP 8.2**. If it shows another version, ask LankaHost which command runs PHP 8.2 and use it instead of `php` below.

```
php artisan key:generate
php artisan app:install
```

`app:install` checks your settings, shows them, and asks **"Create the tables and the first admin now?"** Type `yes`. It creates the tables, the main branch, the admin account, the device list and the message templates. It refuses to run a second time, so it can never wipe the system.

Then:

1. Edit `.env` again: **delete the ADMIN_PASSWORD value** (leave `ADMIN_PASSWORD=` empty) and save.
2. In Terminal:

```
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### A9. Turn on https

1. cPanel → **SSL/TLS Status**: appletek.lk must have a valid certificate (AutoSSL). If not, click **Run AutoSSL**.
2. cPanel → **Domains**: turn **Force HTTPS Redirect** on for appletek.lk.

Login only works over https (`SESSION_SECURE_COOKIE=true`), so this step is required.

### A10. Cron job (emails and background work)

cPanel → **Cron Jobs** → **Add New Cron Job**:

- Common Settings: **Once Per Minute (\* \* \* \* \*)**
- Command:

```
cd /home/mytechno/appletek-app && php artisan schedule:run >> /dev/null 2>&1
```

If `php -v` in A8 was not 8.2, use the full PHP 8.2 path here too (for example `/opt/cpanel/ea-php82/root/usr/bin/php` or `/opt/alt/php82/usr/bin/php` — LankaHost can tell you which).

Without this cron job, **no emails are sent**.

This one line runs everything in `routes/console.php`:

| When | Task |
|---|---|
| Every minute | Send queued emails and jobs (`queue:work`), heartbeat for System health |
| Daily 8:00 AM | Morning email to admins: overdue jobs, low stock, open part requests (`app:admin-summary`) |
| Daily 9:00 AM | Uncollected device reminders: emails + the "WhatsApp reminders" list (`app:uncollected-reminders`) |
| Weekly, Sunday 3:00 AM | Delete temporary files older than 7 days (`app:clean-temp-files`) |
| Daily 2:00 AM | Database backup (`app:backup database`) |
| Weekly, Sunday 2:30 AM | Files backup: photos, PDFs, signatures (`app:backup files`) |
| Weekly, Sunday 7:00 AM | Backup email to admins (`app:backup-email`) |
| Daily 3:30 AM | Delete activity log entries older than 1 year (`activitylog:clean`) |

Backups: see `docs/backups.md` (Admin → Backups, and how to copy them to Google Drive every week). They need the PHP **zip** extension (cPanel → Select PHP Version → Extensions → `zip`). If mysqldump is not allowed, a PHP dump is used automatically.

Check it works: **Admin → System health** shows "The scheduler is running". A red box means the cron has not run for 10 minutes.

### A11. Check that everything works

1. Open **https://appletek.lk** → the login page appears, with the padlock in the address bar.
2. Log in with ADMIN_EMAIL and the password. Go to **Profile** and change the password.
3. **Settings → Shop**: enter the shop name, phone numbers, WhatsApp number and logo.
4. Create a test job card for a customer with **your own email address**:
   - The QR code link under it starts with `https://appletek.lk/track/`.
   - Scan the QR code with your phone: the tracking page opens.
   - **Print job card** opens the PDF.
   - Within 1–2 minutes the job's **Messages** tab shows the email as **Sent**, and you receive it with the PDF attached.

---

## Part B — Uploading an update

1. On your PC, run all tests (`php artisan test`), then double-click **`build-release.bat`**.
2. cPanel → **Terminal**:

   ```
   cd ~/appletek-app
   php artisan down
   ```

   The site now shows "Service Unavailable" to everyone for a few minutes.
3. **File Manager** → `/home/mytechno/appletek-app`:
   - Delete the folders **`vendor`** and **`public/build`** (they are replaced completely; old files in them can cause errors).
   - Upload `release.zip`, **Extract** it here, and say **yes to overwrite**. Delete `release.zip`.

   This never touches `.env`, customer photos, PDFs or logs: they are not in the zip.
4. **Terminal**:

   ```
   php artisan migrate --force
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   php artisan up
   ```

   `migrate --force` adds any new tables or columns. It never deletes data.
5. Open https://appletek.lk, log in and open a job to check.

If the new version added new default data (for example new message templates), also run `php artisan db:seed --force`. It only adds what is missing and never changes your data.

---

## Good to know

- **No `php artisan storage:link`.** It is not needed and many shared hosts block it. Customer photos, the logo and PDFs are on the private disk (`storage/app/private`) and are shown only through logged-in pages. Nothing is in `public/storage`.
- **Never upload your PC's `.env`.** The server has its own. `build-release.bat` leaves `.env` out.
- **After any change to `.env`**, run `php artisan config:cache`, or the change is ignored.
- **The domain is only in `APP_URL`.** QR codes, tracking links, emails and WhatsApp messages use it. QR codes already printed keep the address they were printed with.
- **"500 Server Error"**: look at the newest file in `storage/logs` (File Manager). Do not turn on `APP_DEBUG` on the live site — it shows passwords to visitors.
- **Backups**: cPanel → **Backup**: download the database (`mytechno_appletek`) and the folder `/home/mytechno/appletek-app/storage/app/private` (customer photos and PDFs) regularly.
- **app:install says "Already installed"**: that is correct after the first install. For updates use Part B.