MedYan

Free Deployment Plan

This setup keeps the frontend free on GitHub Pages and runs the API, worker, and Redis on an Oracle Always Free VM.

Free URLs

• Frontend: https://YOUR_USERNAME.github.io/REPO_NAME/
• API: https://YOUR_SUBDOMAIN.duckdns.org

You do not need a paid domain for this setup.

1. GitHub Pages frontend

1. Push this repository to GitHub.
2. In GitHub repository settings, open Pages and select GitHub Actions as the source.
3. Create a repository variable named PAGES_API_URL.
4. Set PAGES_API_URL to your API URL, for example https://medyan-api.duckdns.org.
5. Push to main and wait for the Deploy Frontend to GitHub Pages workflow to finish.

The workflow publishes index.html, public/*, and a generated config.js.

2. Free API domain with DuckDNS

1. Create a free account on DuckDNS.
2. Create a subdomain such as medyan-api.
3. Copy your DuckDNS token.

3. Oracle Always Free VM

1. Create an Ubuntu VM in Oracle Cloud Always Free.
2. Open inbound ports 80 and 443 in the Oracle security list and VM firewall.
3. Install Docker and Docker Compose plugin.

Example commands:

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin git
sudo usermod -aG docker $USER

4. Run the stack

1. Clone the repository on the VM.
2. Copy deploy/oracle/.env.oracle.example to deploy/oracle/.env.oracle.
3. Fill in API_DOMAIN, DUCKDNS_SUBDOMAIN, DUCKDNS_TOKEN, API_KEY, JWT_SECRET, and CORS_ORIGINS.
4. Start the stack:

docker compose -f deploy/oracle/docker-compose.oracle.yml --profile duckdns up -d --build

5. Required environment values

• CORS_ORIGINS must be your exact GitHub Pages URL.
• If you later enable auth across GitHub Pages and the API domain, keep AUTH_COOKIE_SAMESITE=None and HTTPS enabled.
• API_KEY remains server-side only. Do not add it to frontend files.
• In production, prefer PUBLIC_DETECTION_ENABLED=false, PUBLIC_EXTRACT_ENABLED=false, and PUBLIC_NEXUS_SUBMIT_ENABLED=false.
• When these are false, clients must send X-API-Key (or Authorization: Bearer ...) for those endpoints.

6. First tests

1. Open https://YOUR_SUBDOMAIN.duckdns.org/health.
2. Confirm it returns a healthy JSON response.
3. Open your GitHub Pages URL.
4. Paste a URL and test detection.
5. Start an extraction and verify download completes.

7. If you want Cloudflare Pages instead

You can use the same static files and the same API stack.

• Replace the frontend URL in CORS_ORIGINS.
• Set the equivalent Cloudflare Pages environment variable for API_URL.
• Keep the API on the Oracle VM.