# Nūr — Muslim Companion · Deployment Guide

**Target:** `moslem02.falahos.my`  
**CDN:** Cloudflare (proxied / orange-cloud)  
**Server:** Linux with Nginx  
**Stack:** Svelte 5 + Vite PWA (static SPA)

---

## 1. Build

```bash
# Install dependencies (one-time)
npm ci

# Build for production
npm run build
```

Output goes to `dist/`. This includes:

- `index.html` — SPA entry (must not be cached long)
- `assets/index-<hash>.js` / `.css` — hashed, cacheable forever
- `sw.js` — Workbox service worker (must not be cached)
- `manifest.webmanifest` — PWA manifest
- Icons (`icon-192.png`, `icon-512.png`)
- Optional: `workbox-<hash>.js`

---

## 2. Upload to Server

Choose one method.

### SCP (manual)

```bash
scp -r dist/* user@moslem02.falahos.my:/var/www/nur-muslim-companion/
```

### Rsync (incremental, recommended)

```bash
rsync -avz --delete dist/ user@moslem02.falahos.my:/var/www/nur-muslim-companion/
```

---

## 3. Nginx

### Copy the config

```bash
scp deploy/nginx.conf user@moslem02.falahos.my:/etc/nginx/sites-available/nur-muslim-companion
```

### Enable and test

```bash
sudo ln -sf /etc/nginx/sites-available/nur-muslim-companion /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

### Verify

```bash
curl -sI https://moslem02.falahos.my/ | grep -i "cache-control"
# Should show: cache-control: no-cache, must-revalidate
```

---

## 4. Cloudflare Configuration

These settings are in your Cloudflare dashboard for `moslem02.falahos.my`:

| Setting | Value | Reason |
|---------|-------|--------|
| **Proxy status** | Proxied (orange cloud) | CDN caching, DDoS protection, SSL |
| **SSL/TLS** | Full (strict) | End-to-end encryption; requires a valid origin cert |
| **Always Use HTTPS** | On | Redirect HTTP → HTTPS |
| **Auto Minify** | Off | Service worker integrity; Vite already minifies |
| **Brotli** | On (default) | Better compression than gzip |
| **Cache Level** | Standard | Respects origin `Cache-Control` |
| **Edge Cache TTL** | Respect Existing Headers | Our nginx config sets correct policies |
| **Security Level** | Medium | Default; raise if under attack |

### Origin Certificate

Since SSL/TLS is set to **Full (strict)**, the origin server (your VPS) needs a valid certificate. Generate one in Cloudflare Dashboard → SSL/TLS → Origin Server → Create Certificate. Install it on the VPS and point nginx to it.

**If you use Cloudflare's edge certificates only (Flexible SSL), the nginx config can stay HTTP-only on port 80.** The `deploy/nginx.conf` in this repo listens on port 80 — this is safe because Cloudflare proxies all traffic; your VPS never speaks cleartext to the internet.

---

## 5. Service Worker & Cache Invalidation

The PWA uses `registerType: 'autoUpdate'`:

1. **Always re-deploy `sw.js` with `no-cache`** — `deploy/nginx.conf` already does this.
2. When `sw.js` changes, Workbox detects the update, installs the new version, and the PWA updates automatically on next page load or tab switch.
3. Static assets (`/assets/*`) use content-hashed filenames — old cache entries are harmless and evicted naturally.

### Force-refresh after deploy

```bash
# Clear Cloudflare cache for the whole zone
curl -X POST "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"purge_everything":true}'
```

Or use Cloudflare Dashboard → Caching → Purge Everything.

---

## 6. Verification Checklist

- [ ] `curl -I https://moslem02.falahos.my/` returns 200
- [ ] `curl -I https://moslem02.falahos.my/assets/index-*.js` has `cache-control: public, immutable, max-age=31536000`
- [ ] `curl -I https://moslem02.falahos.my/sw.js` has `cache-control: no-cache, no-store, must-revalidate` and `service-worker-allowed: /`
- [ ] Open https://moslem02.falahos.my/ in Chrome → DevTools → Application → Service Workers shows "activated"
- [ ] App installs as PWA (install prompt or Add to Home Screen)
- [ ] Install prompt appears on mobile (Chrome Android / Safari iOS)

---

## 7. Rollback

```bash
# Deploy previous build
rsync -avz --delete path/to/previous-build/ user@moslem02.falahos.my:/var/www/nur-muslim-companion/
# Purge Cloudflare cache
```