# MARI domain setup — marihq.co.za

Checklist for wiring **MARI** public URLs to Firebase and the marketing site.

## Domain map

| Host | Purpose | Firebase project | Repo artifact |
|------|---------|------------------|---------------|
| `portal.marihq.co.za` | Production app (SPA) | Production project (TBD — today `fssc-dev` is local default) | `apps/web/dist` via Hosting |
| `staging.marihq.co.za` | Staging / pilot app | `fssc-staging` (alias `staging` in `.firebaserc`) | `apps/web/dist` via Hosting |
| `marihq.co.za` | Marketing website | Separate Hosting site or static host | `apps/website/dist` |
| `www.marihq.co.za` | Redirect to apex (recommended) | Same as marketing | — |

**Contact email:** `hello@marihq.co.za`  
**App URLs in code:** `https://portal.marihq.co.za` (production), `https://staging.marihq.co.za` (staging)

---

## 1. DNS records

Add these at your `.co.za` registrar (exact targets come from Firebase after you add each custom domain).

### App — staging

| Type | Name | Value |
|------|------|--------|
| CNAME | `staging` | *(Firebase Hosting target, e.g. `fssc-staging.web.app`)* |

### App — production portal

| Type | Name | Value |
|------|------|--------|
| CNAME | `portal` | *(Firebase Hosting target for production project)* |

### Marketing site

Either host on Firebase (second Hosting site) or your existing web host:

| Type | Name | Value |
|------|------|--------|
| A / CNAME | `@` | Your marketing host or Firebase apex records |
| CNAME | `www` | `marihq.co.za` or host provider target |

**Tip:** Firebase may ask for TXT records to verify domain ownership before SSL is issued. Add those exactly as shown in the console.

**Propagation:** Allow up to 24–48 hours; often much faster.

---

## 2. Firebase Hosting — custom domains

### Staging (`fssc-staging`)

1. [Firebase Console](https://console.firebase.google.com/) → project **fssc-staging** → **Hosting**.
2. **Add custom domain** → enter `staging.marihq.co.za`.
3. Copy the CNAME target into DNS (step 1).
4. Wait for **Connected** and **SSL certificate active**.
5. Deploy the app:

   ```bash
   ./scripts/deploy-staging.sh
   ```

6. Confirm: `https://staging.marihq.co.za` loads the login page and `/brand/mari-icon.png` resolves.

### Production portal

1. Open your **production** Firebase project (create one if `fssc-dev` is emulator-only).
2. Hosting → **Add custom domain** → `portal.marihq.co.za`.
3. Complete DNS + SSL as above.
4. Deploy:

   ```bash
   firebase use <production-project-id>
   npm run build
   firebase deploy --only hosting,functions,firestore:rules,firestore:indexes,storage
   ```

### Marketing site (`marihq.co.za`)

The marketing site lives in `apps/website/` and builds to `apps/website/dist`.

**Option A — Firebase Hosting (second site)**  
1. In the marketing Firebase project, add a second Hosting site (or use a dedicated project).
2. Point `firebase.json` hosting `public` to `apps/website/dist` for that site, or use a multi-site `firebase.json` target.
3. Build and deploy:

   ```bash
   npm run build --workspace=website   # or: cd apps/website && npm run build
   firebase deploy --only hosting:<marketing-site-id>
   ```

4. Add custom domains `marihq.co.za` and `www.marihq.co.za`.

**Option B — External host (cPanel, Netlify, etc.)**  
1. `cd apps/website && npm run build`
2. Upload contents of `apps/website/dist` (include `brand/` assets and `.htaccess` if using Apache).

Ensure all pages link to `https://portal.marihq.co.za` for sign-in and registration (already set in `apps/website/src/config.ts`).

---

## 3. Firebase Auth — authorized domains

For each Firebase project that serves the app:

1. **Authentication** → **Settings** → **Authorized domains**.
2. Add:
   - `staging.marihq.co.za`
   - `portal.marihq.co.za`
   - `localhost` (dev — usually already present)

Without this, email/password and OAuth redirects fail on the custom domain.

---

## 4. Cloud Functions — `APP_URL`

Functions use `APP_URL` for billing return URLs, email links, and logo URLs (`functions/src/email/brand.ts`).

| Environment | Set `APP_URL` to |
|-------------|------------------|
| Staging | `https://staging.marihq.co.za` |
| Production | `https://portal.marihq.co.za` |

**Firebase CLI (per function or via `.env` for v2):**

```bash
firebase functions:config:set app.url="https://staging.marihq.co.za" --project staging
```

Or set in Google Cloud Console → Cloud Functions → each function → **Environment variables**, depending on how you deploy.

Redeploy functions after changing env vars.

---

## 5. Web app environment files

### Staging — `apps/web/.env.staging`

```env
VITE_USE_EMULATORS=false
VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=fssc-staging.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=fssc-staging
# ... remaining Firebase web config from Console → Project settings
```

Rebuild after any change: `npm run build`.

### Production — `apps/web/.env.production`

Same pattern with the production Firebase project. `authDomain` can remain `*.firebaseapp.com`; custom domain still works if authorized (step 3).

---

## 6. Email (transactional)

1. **Sender domain:** configure SPF/DKIM for `marihq.co.za` with your email provider (Firebase Extension `firestore-send-email`, SendGrid, etc.).
2. **Default from:** `MARI <noreply@marihq.co.za>` (see `extensions/firestore-send-email.env.example`).
3. Ensure links in templates use `APP_URL` so images load from `/brand/mari-logo-dark.png` on the app host.

---

## 7. Post-setup verification

- [ ] `https://staging.marihq.co.za` — login page, MARI branding, valid SSL
- [ ] `https://portal.marihq.co.za` — same (production)
- [ ] `https://marihq.co.za` — marketing home, links go to portal
- [ ] Register / sign-in works on custom domain (not just `*.web.app`)
- [ ] Password reset email links land on correct host
- [ ] PayFast return URL uses `APP_URL` (if billing enabled)
- [ ] Pilot seed works on staging: `npm run pilot:seed` with `FIREBASE_PROJECT_ID=fssc-staging`

---

## 8. Related docs

- [PILOT_DEPLOY.md](./PILOT_DEPLOY.md) — staging deploy, seed credentials, CI
- [README.md](../README.md) — local dev quick start