Cloudflare on zharif.my

Private APT Repository on Cloudflare Workers

Thu, 05 Mar 2026 00:00:00 +0000

The Problem

Every homelab needs package caching. Every production environment needs custom packages. Yet most of us update from public mirrors with no offline capability.

The real pain points:

Latency: 50MB download for every new node
Air-gapped: No internet = no packages
Custom tooling: Internal .debs need distribution

My setup solves all three: packages live in GitHub Releases (versioned storage), metadata builds in CI (on release), and the worker serves both.

Scale: ~10 machines pulling packages. 500 requests/day before caching kicks in.

Architecture

If you’re running Debian or Ubuntu systems — whether in production, at home, or across a fleet of machines — you’ve probably felt the pain of:

Waiting for packages to download from public mirrors
Needing to patch vulnerable packages urgently across all machines
Wanting to distribute custom-built packages to your infrastructure

Public mirrors are great, but sometimes you need your own. Maybe it’s:

Custom-built packages for internal tooling
Pinned versions for stability
Air-gapped environments that can’t reach the internet

I faced this when building my homelab. I wanted to distribute custom packages to all my Proxmox nodes and GitHub Actions runners without exposing them to the public internet.

The Architecture

Here’s the high-level picture:

  flowchart TB
    subgraph Producers
        Dev[Developer]
        Release[GitHub Release]
    end

    subgraph CI
        Workflow[rebuild-index]
        Branch[apt-metadata branch]
    end

    subgraph Runtime
        Auth[Auth Layer]
        Meta[Metadata API]
        Pkg[Package API]
    end

    subgraph Consumers
        Nodes[Proxmox Nodes]
        Actions[GitHub Actions]
        Apt[apt client]
    end

    Dev --> Release
    Release --> Workflow
    Workflow --> Branch
    Branch --> Meta
    Release --> Pkg
    Nodes --> Auth
    Actions --> Auth
    Auth --> Meta
    Auth --> Pkg

The key insight: static metadata in Git, dynamic packages from releases.

How It Works: The Full Story

1. Package Publishing (Manual + Automated)

When you release a .deb package, it goes to GitHub Releases:

# Upload your package
gh release upload v1.2.3 my-package_1.2.3_amd64.deb

But APT needs more than just the .deb file — it needs metadata. That’s where the rebuild workflow comes in.

2. Metadata Generation (The CI Pipeline)

A GitHub Actions workflow (rebuild-index) listens for releases and generates the metadata:

# scripts/build_index.py (from actual implementation)
async def build_metadata(releases: list[Release]):
    """Build complete APT metadata for all releases."""
    
    packages = []
    for release in releases:
        for asset in release.assets:
            if asset.name.endswith('.deb'):
                pkg = parse_deb_control(asset)
                packages.append(pkg)
    
    # Generate Packages.gz (compressed package index)
    packages_content = "\n\n".join(p.as_apt_control() for p in packages)
    packages_gz = gzip.compress(packages_content.encode())
    
    # Generate InRelease (inline release file)
    inrelease = generate_inrelease(packages_gz, len(packages))
    
    # Sign with GPG
    gpg_signature = gpg_sign(inrelease)
    
    return {
        "Packages.gz": packages_gz,
        "InRelease": inrelease,
        "Release.gpg": gpg_signature
    }

This runs in CI and pushes the generated metadata to a dedicated apt-metadata branch. The branch is never checked out locally — it’s just the persistence layer for the index.

3. Runtime: The Cloudflare Worker

The worker handles three types of requests:

# src/entry.py - Main request router
async def on_fetch(request, env):
    path = urlparse(request.url).path
    
    if path == "/public.key":
        return serve_public_key(env)
    
    if path.startswith("/dists/"):
        return await serve_metadata(request, path, env)
    
    if path.startswith("/pool/"):
        return await serve_package(request, path, env)
    
    return Response.new("Not Found", status=404)

Authentication: OIDC + Basic Auth

This is where the design got interesting. I needed two authentication modes:

GitHub Actions OIDC (Preferred)

For GitHub Actions runners and other automated systems:

# src/auth.py
async def validate_oidc_token(token: str, env) -> bool:
    """Validate GitHub Actions OIDC token."""
    
    # Fetch JWKS from GitHub
    jwks = await fetch_jwks("https://token.actions.githubusercontent.com/.well-known/jwks")
    
    # Verify signature and claims
    claims = jwt.decode(token, jwks, algorithms=["RS256"], audience=env.OIDC_AUDIENCE)
    
    # Check repository and organization claims
    repo = claims.get("repository", "")
    org = claims.get("organization", "")
    
    return org in env.ALLOWED_ORGS and repo in env.ALLOWED_REPOS

The trick: put the OIDC token in the password field of Basic Auth:

# /etc/apt/auth.conf (on runners)
machine apt.example.com
login github-action
password: <oidc_token>

This works because apt sends Basic Auth headers, and the worker detects login == "github-action" to trigger OIDC validation instead of regular Basic Auth.

Basic Auth (Fallback)

For developer machines that can’t use OIDC:

async def validate_basic_auth(auth_header: str, env) -> bool:
    """Validate username/password from Authorization header."""
    credentials = parse_basic_auth(auth_header)
    return (credentials.username == env.APT_USER and 
            credentials.password == env.APT_PASS)

The Package Serving Logic

Here’s how the worker fetches packages from GitHub:

# src/packages.py
async def serve_package(path: str, env, github_token: str):
    """Serve .deb file from GitHub Releases."""
    
    # Parse: /pool/main/a/awesome_1.0.0_amd64.deb
    # Extract: owner, repo, version, filename
    
    # Fetch from GitHub Release Assets
    release_url = f"https://api.github.com/repos/{owner}/{repo}/releases/tags/v{version}"
    release = await github_fetch(release_url, token=github_token)
    
    # Find the matching asset
    asset = next(a for a in release.assets if a.name == filename)
    
    # Stream directly to client
    return Response.new(asset.body, headers={
        "Content-Type": "application/x-debian-package",
        "Content-Length": str(asset.size)
    })

The worker acts as a proxy — it doesn’t store packages, just streams them from GitHub.

Design Considerations

Why Git Branch for Metadata?

Using a Git branch (apt-metadata) for metadata storage means:

Versioning — every index update is a commit
Audit trail — who changed what, when
No external storage — no database, no R2, just Git
Easy rollback — git revert to go back

Why Not Store Packages in Git?

Git LFS could work, but:

Release assets are already in GitHub Releases
Streaming from Releases avoids git clone overhead
Separates metadata from binary storage

Metadata Freshness

The metadata is generated on release. There’s no on-the-fly generation:

  flowchart LR
    Dev[Developer releases v1.2.3] --> CI[CI runs]
    CI --> Branch[Metadata pushed to apt-metadata branch]
    Branch --> Worker[Worker fetches from apt-metadata branch]
    Apt[apt client requests] --> Worker

This trades freshness for simplicity. If you need real-time, you’d need a different architecture.

Security Model

  sequenceDiagram
    participant APT as apt client
    participant Worker as Cloudflare Worker
    participant GitHub as GitHub API
    
    APT->>Worker: GET /public.key
    Worker-->>APT: GPG public key
    
    APT->>Worker: GET /dists/stable/Release (Basic Auth)
    alt GitHub Actions OIDC
        Worker->>Worker: Validate OIDC token
        Worker->>GitHub: Fetch metadata from apt-metadata
        Worker-->>APT: APT metadata
    else Basic Auth
        Worker->>Worker: Validate username/password
        Worker->>GitHub: Fetch metadata from apt-metadata
        Worker-->>APT: APT metadata
    end
    
    APT->>Worker: GET /pool/main/a/awesome_1.2.3.deb (Auth)
    Worker->>GitHub: Stream .deb from Release
    Worker-->>APT: .deb package

The client must authenticate for both metadata and package downloads. The GPG key is public and unauthenticated.

Constraints

Aspect	Limit
CPU Time	30s per request
Memory	128 MB
Bandwidth	Edge network to GitHub
Auth Rate	GitHub API limits apply

For high-volume scenarios, add caching headers. The worker already caches GitHub tokens — package caching could be added similarly.

On-Prem Deployment

Just like the Terraform registry, this runs on workerd:

# docker-compose.yml
services:
  apt-worker:
    image: cloudflare/workerd:latest
    ports:
      - "8787:8787"
    volumes:
      - ./config.workerd:/etc/workerd/config.capnp:ro
    environment:
      - APT_USER=admin
      - APT_PASS_FILE=/run/secrets/apt_password

# wrangler.toml for on-prem
name = "apt-repository"
main = "src/entry.py"

[vars]
GITHUB_OWNER = "your-org"
ALLOWED_ORGS = ["your-org"]

[secrets]
APT_USER = "admin"
# APT_PASS via secret put

Usage

# Add the repository
echo "deb [trusted=yes] https://apt.example.com stable main" | \
    sudo tee /etc/apt/sources.list.d/your-repo.list

# Add GPG key (unauthenticated)
curl -fsSL https://apt.example.com/public.key | \
    sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/your-repo.gpg

# Update and install
sudo apt update
sudo apt install my-internal-tool

The [trusted=yes] is needed because we’re self-signing. In production, you’d want proper GPG setup without the trusted flag.

What Most People Get Wrong

“Metadata refreshes on every request” — No. Metadata is generated on release, stored in Git. Fresh on release, stale until next release.
“Packages live in the worker” — They’re in GitHub Releases. The worker proxies them. No storage cost at the edge.
“OIDC is more complex than API tokens” — For CI systems, OIDC tokens are ephemeral and rotate automatically. Fewer secrets to manage.

When to Use / When NOT to Use

Use Private APT	Use Public Mirror
Air-gapped environments	Internet-connected systems
Custom packages	Standard OS packages
Version pinning required	Rolling releases OK

What’s Next

Both the Terraform registry and APT repository share the same architectural DNA:

Serverless on Cloudflare
Git-backed persistence
Optional on-prem via workerd
No external databases or storage

Private Terraform Registry on Cloudflare Workers

Fri, 20 Feb 2026 00:00:00 +0000

The Alternatives

When you need to share Terraform modules across projects:

Option	Cost	Complexity	Trade-off
Terraform Cloud	$20+/month	Low	Free tier doesn’t support custom modules
Nexus/Artifactory	Free	High	Java-based, heavy for this use case
Custom (this)	Free	Medium	Implement registry protocol yourself

The killer: Terraform Cloud’s free tier doesn’t support private module registries. You need the paid plan. For homelab use, that’s 10x the cost.

What this handles: service discovery, version listing, download URL redirects, and zipball proxy — the full registry protocol.

Worker Endpoints

Endpoint	Purpose
`/.well-known/terraform.json`	Service discovery — tells Terraform where the API lives
`/v1/modules/:ns/:name/:provider/versions`	Lists available versions (from GitHub tags)
`/v1/modules/:ns/:name/:provider/:version/download`	Returns the download URL
`/archive/:ns/:name/:provider/:version`	Proxies the actual module download

The Implementation

Let me walk through the actual code. The worker is written in Python using Pyodide, which means full CPython 3.12 in WebAssembly.

Service Discovery

async def handle_well_known(req, env):
    """Handle /.well-known/terraform.json"""
    response = {
        "modules.v1": f"{env.get('BASE_URL', 'https://terraform.example.com')}/v1/modules/"
    }
    return json_response(response)

Simple enough — returns a JSON object telling Terraform where to find the modules API.

Version Listing

This is where things get interesting. I needed to fetch GitHub tags and filter for valid semver:

def filter_semver_tags(tags: list[str]) -> list[str]:
    """Filter tags to only valid semver versions."""
    valid_tags = []
    for tag in tags:
        if _SEMVER_RE.match(tag):
            valid_tags.append(tag)
    return sorted(valid_tags, key=parse_version, reverse=True)

# Semver pattern from actual implementation
_SEMVER_RE = re.compile(r"^v?\d+\.\d+\.\d+(?:[.+-].+)?$")

The regex ensures only proper semver tags (v1.0.0, 2.3.1, etc.) are returned. Prerelease versions like v1.0.0-beta are supported too.

Authentication: The GitHub App Dance

Here’s where it gets clever. Instead of requiring users to generate GitHub tokens, the worker handles authentication server-side using a GitHub App:

class GitHubAppAuth:
    def __init__(self, app_id: str, private_key: str, installation_id: str):
        self.app_id = app_id
        self.private_key = private_key
        self.installation_id = installation_id
        self._token_cache = None
        self._token_expiry = 0

    async def get_token(self) -> str:
        """Get cached installation token, refreshing if needed."""
        now = time.time()
        if self._token_cache and now < self._token_expiry:
            return self._token_cache
        
        # Generate JWT and exchange for token
        jwt = self._generate_jwt()
        token = await self._exchange_jwt_for_token(jwt)
        
        # Cache for 55 minutes (tokens last 60, safe margin)
        self._token_cache = token
        self._token_expiry = now + 3300
        return token

    def _generate_jwt(self) -> str:
        """Create signed JWT using RS256."""
        # ... WebCrypto implementation

The worker generates a JWT signed with the GitHub App’s private key, exchanges it for an Installation Access Token, and caches that token for 55 minutes. This avoids rate limiting and keeps things snappy.

Design Considerations

Why Server-Side Auth?

The alternative would be API tokens in .terraformrc. But that means:

Users need to generate tokens
Tokens expire and need refreshing
You’re exposing long-lived credentials

With server-side GitHub App auth, Terraform just talks to your worker — no credentials needed on the client side.

Token Caching Strategy

# Using Cloudflare's Cache API for cross-request caching
cache = caches.default
cache_key = f"gh-token-{installation_id}"
cached = await cache.get(cache_key)

if cached:
    token = cached.text
else:
    token = await github_app.get_token()
    # Cache for 55 minutes
    response = Response.new(token, headers={
        "Cache-Control": "max-age=3300"
    })
    await cache.put(cache_key, response)

This is critical because GitHub rate limits would hit hard without caching.

Download URL Handling

Terraform expects the download endpoint to return a X-Terraform-Get header with the location of the actual module archive. I point it back to my worker:

async def handle_module_download(req, env, ns, name, provider, version):
    # Return redirect to archive endpoint
    archive_url = f"/archive/{ns}/{name}/{provider}/{version}"
    return Response.new("", headers={
        "X-Terraform-Get": archive_url
    })

Then the archive endpoint fetches from GitHub’s zipball URL and streams it through.

Constraints and Limits

This isn’t a “run anything anywhere” solution. There are real constraints:

Constraint	Value	Implication
CPU Time	30s (Paid) / 10ms (Free)	Complex auth may timeout on free tier
Memory	128 MB	Enough for Python + JSON parsing
Packages	Pyodide stdlib only	No external dependencies

Terraform Cloud’s free tier doesn’t support private module registries. You need the paid plan.

On-Prem Deployment with workerd

Here’s the part that makes this interesting for self-hosted scenarios: these workers can run locally using workerd, Cloudflare’s Workers runtime as a container.

# docker-compose.yml for local workerd
services:
  workerd:
    image: cloudflare/workerd:latest
    ports:
      - "8787:8787"
    volumes:
      - ./config.workerd:/etc/workerd/config.capnp
    environment:
      - PORT=8787

// config.workerd (JavaScript service binding syntax)
services: [
  {
    name: "terraform-registry",
    script: readFile("dist/worker.js"),
    bindings: {
      GITHUB_APP_ID: "123456",
      GITHUB_INSTALLATION_ID: "789012",
    }
  }
]

This means you can:

Develop and test workers locally
Run the same code on Cloudflare’s edge
Deploy on-prem for air-gapped environments
Use identical infrastructure everywhere

Usage Example

With everything configured, using the registry is straightforward:

# main.tf
module "proxmox_vm" {
  source  = "registry.example.com/namespace/tf-module-proxmox-vm/proxmox"
  version = "1.0.7"

  configuration = {
    name        = "web-server"
    node_name   = "pve1"
    cpu = { cores = 2, type = "host" }
    memory = { dedicated = 4096 }
  }
}

And the CLI configuration:

# ~/.terraformrc
host "registry.example.com" {
  services = {
    "modules.v1" = "https://registry.example.com/v1/modules/"
  }
}

No credentials needed — the worker handles everything server-side.

What Most People Get Wrong

“Free tier has no limits” — 10ms CPU time free, 30s paid. Complex auth on free tier may timeout.
“Pyodide supports all Python packages” — No. ~150 bundled, no arbitrary pip install. Use WebCrypto via JavaScript instead.
“One worker does everything” — For high traffic, add caching. GitHub API rate limits (5K/hour) apply.

When to Use / When NOT to Use

Use Private Registry	Use Terraform Cloud
Free tier budget	Team with >5 users
10-50 modules	100+ modules
Simple requirements	Policy enforcement needed
Air-gapped capable	Cloud-hosted required

What’s Next

This pattern — serverless registry with on-prem fallback — has proven so useful I’ve applied it to APT repositories, which I’ll cover in the next post. The same architecture, different protocol, same benefits.

This pattern can be adapted to your own infrastructure by implementing the Terraform Module Registry Protocol on any serverless or traditional hosting platform.

Python Workers on Cloudflare

Thu, 15 Jan 2026 00:00:00 +0000

The Critical Distinction

Cloudflare announced Python support. You think: “Finally, real Python on serverless!”

Reality check: Pyodide ≠ CPython. It’s CPython compiled to WebAssembly. The implications:

No OS calls, no os module
No pip install — packages must be pre-bundled
Single-threaded execution
HTTP via JavaScript fetch, not requests

This isn’t a problem — it’s just different. Understanding the constraints makes the difference between “why doesn’t this work” and “I know exactly what to use.”

My use case: Terraform Registry (~2K requests/day) + APT Repository (~500 requests/day). Both run on free tier.

Pyodide bundles a subset of Python’s standard library and about 150+ packages (numpy, pandas, etc.). But arbitrary PyPI packages won’t work.

Pyodide Architecture

The implications:

No OS — there’s no Linux, no system calls, no os module as you’d expect
No pip — you can’t pip install requests. Packages must be pre-bundled
No threads — single-threaded execution model
Limited stdlib — not everything is compiled to WASM

The Template

I built a template that handles the boilerplate. Here’s how to start:

# Clone the template
git clone https://github.com/cloudflare/worker-python-template.git
cd worker-python-template

# Install dependencies
npm install

# Run locally
npx wrangler dev

Project Structure

cloudflare-worker-python-template/
├── src/
│   └── entry.py          # Your worker code
├── tests/
│   └── test_worker.py    # Unit tests
├── wrangler.toml         # Worker configuration
├── pyproject.toml        # Python tooling
├── requirements.txt      # Pyodide packages
├── .github/
│   └── workflows/
│       └── deploy.yml    # CI/CD pipeline
└── README.md

The Entry Point

Every Worker needs an entry point. In Python Workers, it’s on_fetch:

# src/entry.py (from actual template)
import json
from urllib.parse import urlparse

async def on_fetch(request, env):
    """Handle incoming requests."""
    
    # Parse the URL path
    path = urlparse(request.url).path
    
    # Route to handlers
    if path == "/":
        return Response.new("Hello from Python Workers!")
    
    elif path == "/health":
        return Response.new(
            json.dumps({"status": "ok"}),
            headers={"Content-Type": "application/json"}
        )
    
    # 404 for everything else
    return Response.new("Not Found", status=404)

Simple, familiar, Pythonic.

Accessing Environment Variables

Just like in Node.js Workers, you access secrets and environment variables via the env object:

# src/entry.py
async def on_fetch(request, env):
    # String variables from wrangler.toml [vars]
    debug_mode = env.get("DEBUG", "false")
    
    # Secrets (set via: npx wrangler secret put API_KEY)
    api_key = env.API_KEY
    
    # Use them
    if debug_mode == "true":
        console.log(f"API Key loaded: {api_key[:4]}...")
    
    return Response.new(f"API Key: {api_key[:4]}***")

Working with JavaScript APIs

This is where Pyodide gets interesting. You can import JavaScript objects directly into Python:

from js import console, fetch, Response, URL

# Use browser/Workers APIs
async def on_fetch(request, env):
    # fetch is available directly
    resp = await fetch("https://api.github.com/users/your-username")
    data = await resp.text()
    
    return Response.new(data, headers={"Content-Type": "application/json"})

The js module exposes global JavaScript objects. This is how you do HTTP requests, interact with the Cache API, use WebCrypto, etc.

Understanding the Constraints

This is critical. Python Workers aren’t Node.js Workers:

Aspect	Python Workers	Node.js Workers
Package Manager	Pyodide bundles only	npm (everything)
Cold Start	~5-10ms	~1ms
Memory	128 MB	128 MB
CPU Time (Free)	10ms	10ms
CPU Time (Paid)	30s	50ms-30s
Filesystem	None	None

Available Packages

Pyodide includes ~150+ packages out of the box:

Standard Library: json, re, urllib, hashlib, base64, datetime
Data: numpy, pandas, scipy
Web: (limited — use fetch from JS instead of requests)

# This works
import json
import re
import hashlib
from urllib.parse import urlparse

# This does NOT work (not bundled)
# import requests  # ❌
# import httpx      # ❌
# import cryptography  # ❌

For HTTP, use the JavaScript fetch:

from js import fetch

async def call_api(url):
    resp = await fetch(url)
    return await resp.json()

Working Around Missing Packages

For things like cryptographic operations, use WebCrypto via JavaScript:

from js import crypto, TextEncoder

async def hash_sha256(data: str) -> str:
    """Hash data using WebCrypto."""
    encoder = TextEncoder.new()
    encoded = encoder.encode(data)
    hash_buffer = await crypto.subtle.digest("SHA-256", encoded)
    return bytes(hash_buffer).hex()

Configuration (wrangler.toml)

The worker configuration lives in wrangler.toml:

name = "my-worker"
main = "src/entry.py"
compatibility_date = "2026-04-25"

# Environment variables (non-sensitive)
[vars]
ENVIRONMENT = "production"
DEBUG = "false"

# KV Namespace for key-value storage
[[kv_namespaces]]
binding = "CACHE"
id = "abc123def456"

# D1 Database for SQL
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "def456abc789"

# R2 Bucket for object storage
[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

# Deploy to specific environment
[env.staging]
name = "my-worker-staging"

[env.staging.vars]
ENVIRONMENT = "staging"

Development Workflow

Local Development

# Start the dev server
npx wrangler dev

# Test with curl
curl http://localhost:8787/
# {"status": "ok"}

The dev server reloads on file changes. It’s fast and works well.

Testing

# tests/test_worker.py (pytest)
import pytest
from src.entry import on_fetch

class MockEnv:
    DEBUG = "false"
    API_KEY = "test-key"

class MockRequest:
    def __init__(self, url):
        self.url = url

def test_health_endpoint():
    request = MockRequest("http://localhost/health")
    response = on_fetch(request, MockEnv())
    
    assert response.status == 200

def test_root_endpoint():
    request = MockRequest("http://localhost/")
    response = on_fetch(request, MockEnv())
    
    assert response.status == 200
    assert "Hello" in response.body

Run tests:

pip install pytest
pytest -v

Linting

pip install ruff
ruff check src/ tests/
ruff format src/ tests/

The template includes CI that runs both tests and linting.

CI/CD Pipeline

The included GitHub Actions workflow:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      
      - name: Lint
        run: |
          pip install ruff
          ruff check src/ tests/
      
      - name: Test
        run: |
          pip install pytest
          pytest -v
      
      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

On-Prem Deployment with workerd

Here’s where this gets powerful: you can run the same Python Worker locally using workerd, Cloudflare’s open-source Workers runtime.

Why Run Locally?

Development — faster iteration than deploy-then-test
Testing — consistent environment for integration tests
Air-gapped — run in environments without internet
Privacy — keep traffic local for sensitive workloads

Docker Setup

# docker-compose.yml
services:
  worker:
    image: cloudflare/workerd:latest
    ports:
      - "8787:8787"
    volumes:
      - ./config.workerd:/etc/workerd/config.capnp:ro
    cap_add:
      - SYS_ADMIN

The Config

// config.workerd (JavaScript format, not TOML)
export default {
  services: [
    {
      name: "my-worker",
      script: readFile("dist/worker.mjs"),
      bindings: {
        ENVIRONMENT: "development",
        API_KEY: "dev-key",
      }
    }
  ],
  sockets: [
    {
      address: "0.0.0.0:8787",
      http: {
        endpoint: "0.0.0.0:8787"
      }
    }
  ]
};

Building for workerd

The trick: Wrangler outputs JavaScript, but workerd needs its own format. The template handles this:

# Build for Cloudflare (default)
npx wrangler deploy

# Build for workerd (local)
npm run build:workerd

This outputs a compatible worker.mjs for local testing.

Real-World Usage

I’ve built several production workers using this template:

terraform-registry — ~2K requests/day, handles module distribution
apt-repository — ~500 requests/day, serves packages to 10+ machines
cloudflare-ddns — Updates DNS records based on IP changes

All run on the free tier. All deploy in seconds. All can run locally.

What I Love

Python syntax — feels like writing regular Python
Global distribution — edge deployment out of the box
Zero infra — no servers, no scaling concerns
On-prem option — workerd for local/air-gapped needs

What Most People Get Wrong

“Pyodide = CPython” — No OS, no pip, no threads. Use js module for HTTP/WebCrypto.
“Free tier is unlimited” — 10ms CPU cap. Complex Python on free tier = timeouts.
“Works locally = works on edge” — Local dev uses Node, edge uses V8. Test with workerd.

When to Use Python Workers

Use Python Workers	Use Node.js Workers
Python expertise	JavaScript expertise
Data processing	I/O-heavy
Simple logic	Complex async
~150 bundled packages needed	Full npm ecosystem

Getting Started

If you want to build your own Python Workers:

Use the Workers Python template
Write your on_fetch handler
Deploy with wrangler deploy

This post covers building workers with Python. In future posts, I’ll dive into specific patterns like handling async operations, using KV/D1/R2 bindings, and testing strategies for Workers.