DEPLOY_ON_SUBDOMAIN.md

# 🌐 How to Deploy on a Custom Subdomain (Step-by-Step)

This guide explains how to make your API accessible via a custom subdomain (e.g., `api.yourwebsite.com`) instead of the default provider URL (e.g., `huggingface.co/spaces/...`).

---

## ✅ Prerequisites
1. **A Domain Name**: You must own a domain (e.g., `yourwebsite.com`) purchased from a registrar like GoDaddy, Namecheap, Hostinger, or managed via Cloudflare.
2. **Access to DNS Settings**: You must be able to add records (A, CNAME, TXT) in your domain's dashboard.
3. **A Deploy Service**: Where your code currently lives (e.g., Hugging Face Spaces, Render, DigitalOcean, etc.).

---

## 🚀 Scenario A: Using Hugging Face Spaces (Your Current Setup)
Since you are currently deploying to Hugging Face Spaces (`ubuntu593/alt-scraper-api`), follow these steps to use a custom subdomain.

### 1. Configure the Space
1. Go to your Space: **[https://huggingface.co/spaces/ubuntu593/alt-scraper-api](https://huggingface.co/spaces/ubuntu593/alt-scraper-api)**.
2. Click on the **Settings** tab.
3. Scroll down to the **"Custom Domain"** section.
4. Enter your desired subdomain: `api.yourwebsite.com`.
5. Click **"Add domain"**.

### 2. Update DNS Records
Hugging Face will display a "Target" or "Value" that you need to point your domain to. Usually, it requires a **CNAME** record.

1. Log in to your Domain Registrar (GoDaddy, Namecheap, Cloudflare, etc.).
2. Go to **DNS Management** or **Name Server Settings**.
3. Add a new record:
   - **Type**: `CNAME`
   - **Name** (or Host): `api` (Using just `api` creates `api.yourwebsite.com`)
   - **Value** (or Target): `ubuntu593-alt-scraper-api.hf.space` (or whatever specific target HF provides in the settings).
   - **TTL**: `Automatic` or `3600`.

### 3. Verify
1. Wait for DNS propagation (can take 5 mins to 24 hours, usually fast with Cloudflare).
2. Hugging Face will verify the connection. Once verified, the status in Settings will change to "Active" (green).
3. You can now access your API at: `https://api.yourwebsite.com/api/seo-report`.

---

## 💻 Scenario B: Using a Virtual Private Server (VPS)
If you decide to host this on a VPS (DigitalOcean, AWS, Linode) for full control, follow these steps.

### 1. Get the Server IP
Assume your server's Public IP is `192.0.2.123`.

### 2. Update DNS Records
1. Log in to your Domain Registrar.
2. Add a new record:
   - **Type**: `A`
   - **Name** (or Host): `api`
   - **Value**: `192.0.2.123`
   - **TTL**: `Automatic` or `3600`.

### 3. Configure the Server (Nginx Reverse Proxy)
Since your Docker container runs on port `7860` (or `5050`), you don't want users typing the port. You use Nginx to forward port 80/443 to your app.

1. **Install Nginx**:
   ```bash
   sudo apt update
   sudo apt install nginx -y
   ```

2. **Create a Config File**:
   ```bash
   sudo nano /etc/nginx/sites-available/api.yourwebsite.com
   ```

3. **Paste this Configuration**:
   ```nginx
   server {
       server_name api.yourwebsite.com;

       location / {
           proxy_pass http://127.0.0.1:7860; # Forward requests to your Docker app
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
   }
   ```

4. **Enable the Site**:
   ```bash
   sudo ln -s /etc/nginx/sites-available/api.yourwebsite.com /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl restart nginx
   ```

### 4. Enable HTTPS (SSL)
Use Certbot to get a free SSL certificate so `https://` works.
```bash
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d api.yourwebsite.com
```

---

## ❓ Common Questions

**Q: Does SSL (HTTPS) work automatically?**
- **Hugging Face**: Yes, they handle SSL for you automatically.
- **VPS**: No, you must run Certbot (Step 4 above).

**Q: How long does it take?**
- DNS changes can take up to 48 hours globally, but usually update within 15 minutes.

**Q: Can I use `www.api.yourwebsite.com`?**
- Yes, but that is a sub-subdomain. Unless necessary, keep it simple with just `api.yourwebsite.com`.