nur-falah/deploy/DEPLOY.md

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

# 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)

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

Rsync (incremental, recommended)

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

---

3. Nginx

Copy the config

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

Enable and test

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

Verify

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

# 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

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