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.
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:

   sudo apt update
   sudo apt install nginx -y
   

2. Create a Config File:

   sudo nano /etc/nginx/sites-available/api.yourwebsite.com
   

3. Paste this Configuration:

   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:

   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.

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.