Self-Hosting

FxEmbed is designed to run on Cloudflare Workers, which are free for up to 100,000 requests per day per account. Because Workers run on Cloudflare’s global edge network, your instance will automatically be distributed worldwide for low latency.

Prerequisites

Latest Node.js LTS (Currently 24.14.x)
A Cloudflare account
Your Cloudflare Account ID

Steps

1. Clone and Install

git clone https://github.com/FxEmbed/FxEmbed.git
cd FxEmbed
npm install

2. Configure Wrangler

Copy the example Wrangler config and fill in your details:

cp wrangler.example.toml wrangler.toml

Edit wrangler.toml and set your Cloudflare Account ID:

name = "fxembed"
account_id = "YOUR_ACCOUNT_ID_HERE"
main = "./dist/worker.js"
compatibility_date = "2026-04-11"

If you don’t need Cloudflare Analytics Engine, remove the analytics_engine_datasets section.

3. Configure Environment Variables

Copy the example environment file and customize it:

cp .env.example .env

See the Configuration guide for details on each variable.

4. Configure Branding (Optional)

Copy and edit the branding configuration:

cp branding.example.json branding.json

You can configure the name, colors, icons, and redirect URLs for each zone you want to support. See Configuration for details.

5. Authenticate and Deploy

Deploy to Cloudflare:

npm run deploy

This builds the worker with esbuild and deploys it via wrangler deploy --no-bundle.

6. Set Up Custom Domain

Once your worker is running on *.workers.dev, add it to your custom domain through the Cloudflare dashboard.

Building Locally

To build without deploying (useful for testing):

npm run build-local

This runs esbuild without the Sentry upload step.

Viewing Logs

To tail real-time logs from your deployed worker:

npm run log

This runs wrangler tail to stream logs to your terminal.

Updating

Pull the latest changes and redeploy:

git pull
npm install
npm run deploy