# Document Root Configuration Guide

**Version:** 2.0.0
**Date:** December 2025
**Critical:** All domains/subdomains MUST point to `/redirect` folder

---

## Quick Reference

### Folder Purpose

```
/public     → Dashboard (admin interface only)
/redirect   → Shortlinks (PUBLIC document root)
```

### cPanel Configuration

**When adding domain via dashboard:**
- Document Root: `redirect` (NOT `public`)
- Wildcard subdomain: `*.domain.com` → `redirect`
- This is AUTOMATIC - handled by `DomainService.php`

---

## Why `/redirect` Folder?

### Architecture Benefits

✅ **Security**
- Admin dashboard isolated from public redirects
- Prevents unauthorized access to admin functions
- Separate authentication domains

✅ **Performance**
- Different caching strategies per folder
- CDN-friendly for redirect domains
- Independent scaling

✅ **Flexibility**
- Multiple redirect domains possible
- Dashboard on separate subdomain
- Clean separation of concerns

### Folder Responsibilities

#### `/public` - Dashboard

**Purpose:** Admin interface

**Access:**
```
https://dashboard.yourdomain.com → /public/index.php
```

**Contains:**
- Dashboard UI (index.php)
- AJAX endpoints (ajax/*.php)
- Admin-only features
- System settings management

**NOT used for:**
- Shortlink redirects
- Public-facing URLs
- Document root for domains

#### `/redirect` - Shortlinks

**Purpose:** Public shortlink handler

**Access:**
```
https://go.yourdomain.com/abc123     → /redirect/s.php?slug=abc123
https://go.yourdomain.com/s/abc123   → /redirect/s.php?slug=abc123
https://go.yourdomain.com/shim.php   → /redirect/shim.php
```

**Contains:**
- s.php (redirect handler)
- shim.php (intermediate page)
- .htaccess (URL rewriting)
- Clean URL routing

**Used for:**
- ALL domains added via dashboard
- Wildcard subdomains
- Shortlink redirects

---

## cPanel Document Root Path

### Automatic Configuration

When you add domain via dashboard, `DomainService.php` automatically sets:

```php
// src/Service/DomainService.php (line 55)
$docroot = "redirect";

// cPanel API call
$cpanelApi->addAddonDomain($domain, $subdomain, $docroot);
$cpanelApi->addWildcardSubdomain($domain, $docroot);
```

### Full Path Example

**User:** `cpanel_user`
**Domain added:** `example.com`
**Document Root in cPanel:**

```
/home/cpanel_user/domain-dashboard-final/redirect
```

**NOT:**
```
❌ /home/cpanel_user/domain-dashboard-final/public
❌ /home/cpanel_user/domain-dashboard-final/
❌ /home/cpanel_user/public_html
```

---

## Verification

### Check Document Root in cPanel

1. Login to cPanel
2. Go to **Domains** section
3. Find your domain
4. Click **Manage**
5. **Document Root** should show:
   ```
   /home/username/domain-dashboard-final/redirect
   ```

### Check Wildcard Subdomain

1. cPanel → **Domains** → **Subdomains**
2. Find: `*.example.com`
3. Document Root should be:
   ```
   /home/username/domain-dashboard-final/redirect
   ```

### Test URLs

**Test shortlink redirect:**
```bash
curl -I https://example.com/test123

# Should redirect to destination URL
# OR show 404 if shortlink doesn't exist
```

**Test shim page (if enabled):**
```bash
curl -I https://example.com/shim.php?slug=test&dest=aHR0cHM6Ly9leGFtcGxlLmNvbQ==

# Should show 200 OK (shim page)
```

**Test dashboard (separate domain):**
```bash
curl -I https://dashboard.yourdomain.com/

# Should show dashboard UI
```

---

## Manual Configuration (if needed)

### If domain was added manually in cPanel

**Fix document root:**

1. Login to cPanel
2. Go to **Domains**
3. Click domain name
4. Change **Document Root** to:
   ```
   redirect
   ```
   (cPanel automatically adds full path)

5. Save changes

### If wildcard subdomain is wrong

1. cPanel → **Subdomains**
2. Delete existing `*.example.com` if exists
3. Create new:
   - Subdomain: `*`
   - Domain: `example.com`
   - Document Root: `redirect`

---

## Common Mistakes

### ❌ WRONG: Using `/public` as document root

```apache
# WRONG - Dashboard folder
DocumentRoot /home/user/domain-dashboard-final/public
```

**Problem:** Users will see dashboard login, not shortlink redirects

### ❌ WRONG: Using root folder

```apache
# WRONG - Root folder
DocumentRoot /home/user/domain-dashboard-final
```

**Problem:** Exposes all files including .env, database migrations

### ✅ CORRECT: Using `/redirect`

```apache
# CORRECT - Redirect folder
DocumentRoot /home/user/domain-dashboard-final/redirect
```

**Result:** Clean shortlink redirects, proper routing

---

## Multiple Domain Setup

### Recommended Structure

```
Dashboard:     https://admin.yourdomain.com    → /public
Redirect #1:   https://go.yourdomain.com       → /redirect
Redirect #2:   https://link.yourdomain.com     → /redirect
Redirect #3:   https://short.yourdomain.com    → /redirect
```

**All redirect domains point to same `/redirect` folder**

### Benefits

- Unified shortlink database
- Centralized management
- Domain rotation for anti-block
- Load distribution

---

## Virtual Host Examples

### Apache - Separate Subdomains

```apache
# Dashboard
<VirtualHost *:80>
    ServerName admin.yourdomain.com
    DocumentRoot /home/user/domain-dashboard-final/public

    <Directory /home/user/domain-dashboard-final/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

# Redirects
<VirtualHost *:80>
    ServerName go.yourdomain.com
    ServerAlias link.yourdomain.com
    ServerAlias short.yourdomain.com
    DocumentRoot /home/user/domain-dashboard-final/redirect

    <Directory /home/user/domain-dashboard-final/redirect>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

### cPanel Configuration

**Dashboard Subdomain:**
```
Subdomain:      admin.yourdomain.com
Document Root:  public
```

**Redirect Domains (Addon Domains):**
```
Domain:         go.yourdomain.com
Document Root:  redirect
Wildcard:       *.go.yourdomain.com → redirect
```

---

## Troubleshooting

### Issue: Shortlink shows 404

**Check:**
1. Document root is `/redirect`
2. s.php exists in redirect folder
3. .htaccess exists with rewrite rules
4. mod_rewrite enabled

### Issue: Seeing dashboard instead of redirects

**Problem:** Document root pointing to `/public`

**Solution:**
```bash
# Change in cPanel Domains
Document Root: redirect  # NOT public
```

### Issue: File not found errors

**Check bootstrap path in redirect files:**
```php
// In /redirect/s.php and /redirect/shim.php
require_once __DIR__ . '/../bootstrap/init.php';

// Correct: Goes up one level (..) to find bootstrap
```

---

## Security Notes

### Document Root Restrictions

**`/public` folder:**
- Protected by authentication (if implemented)
- Admin access only
- CSRF protection on forms
- Rate limiting on AJAX

**`/redirect` folder:**
- Public access (no auth)
- Mini WAF protection
- IP blocking for attacks
- Bot detection

### File Permissions

```bash
# Folders
chmod 755 public redirect

# PHP files
chmod 644 redirect/s.php
chmod 644 redirect/shim.php
chmod 644 public/index.php

# Sensitive files
chmod 600 .env
```

---

## Migration from Old Setup

### If you previously used `/public` for redirects

**Steps:**

1. **Backup current setup**
   ```bash
   cp -r public/s.php public/s.php.bak
   ```

2. **Verify new files in `/redirect`**
   ```bash
   ls -la redirect/
   # Should show: s.php, shim.php, .htaccess
   ```

3. **Update all domains in cPanel**
   - Change document root from `public` to `redirect`

4. **Test shortlinks**
   ```bash
   curl -I https://yourdomain.com/test123
   ```

5. **Remove old redirect files from `/public`**
   ```bash
   rm public/s.php  # If exists
   ```

---

## Summary

**Key Points:**

✅ **ALL domains added via dashboard → `/redirect` folder**
✅ **Dashboard UI → `/public` folder (separate subdomain)**
✅ **Document root is automatic - no manual configuration needed**
✅ **Wildcard subdomains → `/redirect` folder**
✅ **Separation provides security, performance, flexibility**

**Quick Check:**

```bash
# Correct structure
/home/user/domain-dashboard-final/
├── public/       # Dashboard
│   └── index.php
└── redirect/     # Shortlinks (DOCUMENT ROOT)
    ├── s.php
    ├── shim.php
    └── .htaccess
```

**Domain Configuration:**

```
Domain added:       example.com
cPanel docroot:     redirect
Wildcard:           *.example.com → redirect
Access URL:         https://example.com/abc123
Handler:            /redirect/s.php?slug=abc123
```

---

**For full deployment guide, see:** `FOLDER_STRUCTURE.md`

**For system settings, see:** `SYSTEM_SETTINGS_DEPLOYMENT.md`

---

**End of Document Root Configuration Guide**