# KOS — server setup (step by step)

Takes about 30 minutes on a fresh Ubuntu 22.04 / 24.04 VPS. Commands are for Ubuntu; on cPanel or
Plesk hosting see step 9.

## 1. What the server needs
* PHP **8.1 or newer** with: `pdo_mysql curl mbstring fileinfo openssl` (+ `apcu`, optional)
* **MySQL 8.0+** or **MariaDB 10.6+**
* **Nginx** or **Apache** (with mod_rewrite + mod_headers)
* An SSL certificate (free from Let's Encrypt)
* A domain or sub-domain, e.g. `kos.kingdigital.in`, pointing to the server

```bash
sudo apt update
sudo apt install -y nginx mysql-server php-fpm php-mysql php-curl php-mbstring php-apcu unzip certbot python3-certbot-nginx
php -v          # note the version, e.g. 8.3 — you need it in step 4
```

## 2. Upload KOS
Unzip into `/var/www/kos` so that you have `/var/www/kos/public`, `/var/www/kos/app`, `/var/www/kos/config` …
```bash
sudo mkdir -p /var/www/kos && sudo unzip KOS-server.zip -d /tmp/kos && sudo cp -r /tmp/kos/KOS-server/* /var/www/kos/
```

## 3. Create the database
```bash
sudo mysql
```
```sql
CREATE DATABASE kos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kos'@'localhost' IDENTIFIED BY 'choose-a-long-password';
GRANT ALL PRIVILEGES ON kos.* TO 'kos'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

## 4. Web server
**Nginx (recommended):**
```bash
sudo cp /var/www/kos/server-config/nginx-kos.conf /etc/nginx/sites-available/kos
sudo nano /etc/nginx/sites-available/kos      # change kos.kingdigital.in and php8.1 to your domain / PHP version
sudo ln -s /etc/nginx/sites-available/kos /etc/nginx/sites-enabled/
sudo certbot certonly --nginx -d kos.kingdigital.in
sudo nginx -t && sudo systemctl reload nginx
```
**Apache:** point the site's DocumentRoot to `/var/www/kos/public` with `AllowOverride All`.
`public/.htaccess` already has all the rules.

PHP security settings:
```bash
sudo cp /var/www/kos/server-config/php-kos.ini /etc/php/8.3/fpm/conf.d/99-kos.ini   # use your version
sudo systemctl restart php8.3-fpm
```

## 5. Run the installer
```bash
cd /var/www/kos
sudo -u www-data php install/install.php
```
It checks the server, asks for the database details and your web address, creates all tables,
and creates **your admin login** (name, work email, password). Then set file permissions:
```bash
sudo chown -R root:www-data /var/www/kos && sudo chmod -R o-rwx /var/www/kos
sudo chown -R www-data:www-data /var/www/kos/storage
sudo chmod 640 /var/www/kos/config/app.php
```
Open **https://kos.kingdigital.in** → sign in with the email and password you just set.

## 6. Email and SMS (edit `config/app.php`)
* **Email** (`mail`): needed so staff can set their own password. With Gmail / Google Workspace
  use `smtp.gmail.com`, port 587, `tls`, and an **App password** (Google account → Security).
* **SMS** (`sms`): needed for customer OTP login. Set `driver` to `msg91` or `fast2sms` and fill in
  the keys and your **DLT-approved** template. While testing, `log` writes the OTP to
  `storage/logs/sms.log` instead — never leave `log` on a live site.
* **AI** (`ai`, optional): paste an Anthropic API key to switch on Ask KOS, the daily briefing,
  bill reading and the selfie face check. Leave empty to keep AI off.

**Behind Cloudflare or a load balancer?** Put the proxy's IP addresses in `trusted_proxies`, so rate limits see each
visitor's real IP. **Recommended:** set `staff.email_2fa` to `true` so staff also enter a code from their email.

## 7. Add your team and customers
* **Staff:** KOS → Employees → add each person with their **work email** and a role. Their login is
  created automatically. They open the sign-in page → *Forgot or first-time password?* → get an
  email link → choose their password. (Or set one for them: `php install/install.php password their@email`.)
  Turn "Allow this person to log in" off to block someone instantly.
* **Customers:** HR or an admin opens a customer → *Create customer login* with their mobile number. They sign in at
  `/portal/login.php` with an SMS OTP and see only their own invoices, quotations, services and tickets.
* Fine-tune what each person can open in **Staff access**.

## 8. Cron jobs (`sudo crontab -e`)
```
15 2 * * *  php /var/www/kos/cron/cleanup.php >> /var/www/kos/storage/logs/cron.log 2>&1
30 2 * * *  /var/www/kos/cron/backup.sh
```
Put the MySQL login for backups in `/root/.my.cnf`. Copy `/var/backups/kos` off the server regularly
(Google Drive, another server).

## 9. Shared hosting (cPanel / Plesk)
Upload the folder **above** `public_html`, e.g. `/home/USER/kos/`, and set the domain's document
root to `/home/USER/kos/public`. Create the database in cPanel → MySQL Databases, then run the
installer from cPanel → Terminal: `php kos/install/install.php`. If you have no terminal, ask your
host to run it once.

## 10. Updating the app later
Replace `frontend/kos-source.html` (or `kos.min.html`) and run `php tools/build.php`. Your data is not touched.

## Troubleshooting
| Problem | Fix |
|---|---|
| "KOS is not installed yet" | Run step 5. |
| White page / error 500 | `tail /var/log/nginx/error.log` and `storage/logs/`. Usually a missing PHP extension: `php install/install.php check`. |
| 403 Forbidden in the browser | You are using a VPN / browser extension that hides the browser language, or a tool that looks like a bot. Use normal Chrome / Edge / Safari. |
| Staff password email never arrives | Check `mail` settings; test with `driver => 'log'` and read `storage/logs/mail.log`. |
| OTP SMS never arrives | DLT template / sender ID not approved yet, or wrong keys. Check the gateway's dashboard. |