Skip to main content

Quickstart: Cloudflare Workers

Deploy PACKAGE.broker on Cloudflare Workers for edge-optimized, serverless package proxying.

Choose Your Deployment Method​

We offer two ways to deploy:

  1. CLI Setup (recommended) - Initialize configuration files and follow setup steps
  2. GitHub Template - Fork-and-deploy with automated GitHub Actions

Prerequisites​

Step 1: Install and Initialize​

$ npm init -y
$ npm install @package-broker/cli @package-broker/main
$ npx package-broker init

Note: Packages are available from npmjs.org (default) or GitHub Packages. To install from GitHub Packages, use:

$ npm install @package-broker/cli @package-broker/main --registry https://npm.pkg.github.com

The CLI will:

  • Create wrangler.toml from template
  • Copy migration files to migrations/ directory
  • Display next steps for configuration

What Happens Automatically​

  1. ✅ Creates wrangler.toml configuration file
  2. ✅ Copies database migration files to migrations/ directory
  3. ✅ Displays next steps for manual configuration

Note: The CLI currently provides basic initialization. For automated resource creation and deployment, see the Advanced: Manual Setup section below, or use the GitHub Template method for fully automated deployment.

Step 2: Configure and Deploy​

After running npx package-broker init, follow the displayed instructions to:

  1. Edit wrangler.toml with your configuration:

    • Set your worker name
    • Configure encryption key (generate with: openssl rand -base64 32)
    • Optionally configure SMTP for email sending (see SMTP Configuration below)

  2. Login to Cloudflare:

    $ npx wrangler login

  3. Create Cloudflare resources (see Advanced: Manual Setup for detailed steps):

    • D1 database
    • KV namespace
    • R2 bucket
    • Queue (if using paid tier)

  4. Update wrangler.toml with the generated resource IDs

  5. Set encryption key as secret:

    $ npx wrangler secret put ENCRYPTION_KEY

  6. Set SMTP secrets (optional, for email sending):

    $ npx wrangler secret put SMTP_PASS

    See SMTP Configuration below for details.

  7. Apply database migrations:

    $ npx wrangler d1 migrations apply <worker-name>-db --remote

  8. Deploy to Cloudflare:

    $ npx wrangler deploy

After Deployment​

  1. Open your Worker URL (shown in deployment output)
  2. Complete initial setup (email + password)
  3. Create an access token in the dashboard
  4. Start adding repository sources

Advanced: Manual Setup​

If you prefer manual control or need to customize the setup process, follow these detailed steps:

Manual Resource Creation​

  1. Create D1 database:

    $ npx wrangler d1 create <worker-name>-db

    Copy the database_id from the output.

  2. Create KV namespace:

    $ npx wrangler kv namespace create <worker-name>-kv

    Copy the id from the output.

  3. Create R2 bucket:

    $ npx wrangler r2 bucket create <worker-name>-artifacts

  4. Create Queue (paid tier only):

    $ npx wrangler queues create <worker-name>-queue

Manual Configuration​

  1. Edit wrangler.toml with resource IDs from above:

    • Update database_id in [[d1_databases]] section
    • Update id in [[kv_namespaces]] section
    • Update bucket_name in [[r2_buckets]] section (if different)
    • Update queue name in [[queues.producers]] and [[queues.consumers]] sections (if using paid tier)

  2. Generate encryption key:

    $ openssl rand -base64 32

    Copy the generated key.

  3. Set encryption key as Cloudflare secret:

    $ npx wrangler secret put ENCRYPTION_KEY

    Paste the encryption key when prompted.

  4. Apply database migrations:

    $ npx wrangler d1 migrations apply <worker-name>-db --remote

  5. Deploy Worker:

    $ npx wrangler deploy

See CLI Reference for more details on the init command.

Method 2: GitHub Template (CI/CD)​

Prerequisites​

  • A GitHub account
  • A Cloudflare account
  • Repository must be initialized: The template includes package.json and package-lock.json with required dependencies

Step 1: Use Template​

  1. Go to package-broker/cloudflare-template
  2. Click "Use this template"
  3. Create your repository

Important: The template repository already includes package.json and package-lock.json with all required dependencies. Do not delete these files.

Step 2: Configure Secrets and Variables​

In your repository: Settings → Secrets and variables → Actions

Required Secrets​

Required Variables​

  • CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID (found in dashboard)

Optional Variables​

  • WORKER_NAME - Custom worker name (defaults to repository name)
  • CLOUDFLARE_TIER - free or paid (defaults to free)
  • CUSTOM_DOMAIN - Custom domain to use (e.g., app.example.com). After deployment, you'll receive instructions to create a CNAME record in Cloudflare DNS.

Step 3: Deploy​

Push to main branch or manually trigger the workflow from the Actions tab.

The workflow automatically:

  • Validates configuration
  • Installs dependencies using npm ci (requires package-lock.json)
  • Creates Cloudflare resources via @package-broker/cloudflare CLI
  • Generates wrangler.toml at runtime (not committed to repository)
  • Sets secrets
  • Applies migrations
  • Deploys the Worker

API Token Permissions​

Required Permissions

Your CLOUDFLARE_API_TOKEN must be a scoped API token (not Global API Key) with at least Edit permissions for:

  • Workers - Workers Scripts (deploy/update Worker)
  • D1 - Create/list databases, run migrations
  • KV - Create/list namespaces
  • R2 - Create/list buckets
  • Queues (paid tier only) - Create/list queues

Optional (recommended for better error messages):

  • Account - Account Settings (Read)

Important:

  • Do not use the Global API Key
  • Keep the token account-scoped and minimal
  • Route/zone permissions are only needed for custom domains (not required for workers.dev)

Security: Encryption Key​

The ENCRYPTION_KEY is never stored in wrangler.toml. It's set as a Cloudflare secret:

  • CLI: Automatically set via wrangler secret put ENCRYPTION_KEY
  • GitHub Actions: Set automatically during workflow
  • Manual: Use wrangler secret put ENCRYPTION_KEY or set via Cloudflare dashboard

To update the key:

  • Via CLI: wrangler secret put ENCRYPTION_KEY
  • Via Dashboard: Workers & Pages → Settings → Variables and Secrets

SMTP Configuration (Optional)​

To enable email sending for user invitations, configure SMTP in wrangler.toml:

[vars]
# ... existing vars ...
SMTP_HOST = "smtp.sendgrid.net"
SMTP_PORT = "587"
SMTP_USER = "apikey"
SMTP_FROM = "noreply@example.com"

Important: For production, store SMTP_PASS as a Cloudflare secret instead of in [vars]:

$ npx wrangler secret put SMTP_PASS

When prompted, enter your SMTP password or API key.

Email Provider Examples​

[vars]
SMTP_HOST = "smtp.sendgrid.net"
SMTP_PORT = "587"
SMTP_USER = "apikey"
SMTP_FROM = "noreply@yourdomain.com"

Then set the API key as a secret:

$ npx wrangler secret put SMTP_PASS
# Enter: SG.your-sendgrid-api-key

Gmail​

[vars]
SMTP_HOST = "smtp.gmail.com"
SMTP_PORT = "587"
SMTP_USER = "your-email@gmail.com"
SMTP_FROM = "your-email@gmail.com"

Then set the app-specific password as a secret:

$ npx wrangler secret put SMTP_PASS

Note: Gmail requires an app-specific password for SMTP.

AWS SES​

[vars]
SMTP_HOST = "email-smtp.us-east-1.amazonaws.com"
SMTP_PORT = "587"
SMTP_USER = "AKIAIOSFODNN7EXAMPLE"
SMTP_FROM = "noreply@yourdomain.com"

Then set the IAM secret access key as a secret:

$ npx wrangler secret put SMTP_PASS

Note: Email sending is optional. If SMTP is not configured, user creation will still work, but no emails will be sent. See Configuration Reference for complete SMTP documentation.

Initial Setup​

After deployment, complete the initial setup:

  1. Open your Worker URL in a browser
  2. Enter your email address
  3. Set a secure password
  4. Click "Complete Setup"

Create an Access Token​

  1. Navigate to Access Tokens in the dashboard
  2. Click Create Token
  3. Enter a description
  4. Select permissions (readonly or write)
  5. Click Create
  6. Copy the token immediately

Verify Installation​

Test the health endpoint:

$ curl https://your-worker.workers.dev/health

Expected output:

{
  "status": "ok",
  "timestamp": 1234567890
}

Free Tier Limitations​

Cloudflare Workers free tier includes:

  • 100,000 requests/day per account
  • 10ms CPU time per request
  • 128MB memory per request
  • D1: 5GB storage, 5 million reads/month, 100,000 writes/month
  • R2: 10GB storage, 1 million Class A operations/month
  • KV: 100,000 reads/day, 1,000 writes/day

For production workloads, consider the Workers Paid plan ($5/month) for:

  • Unlimited requests
  • Higher CPU time limits
  • Queue support for async operations

Troubleshooting​

CLI: Authentication Failed​

If the CLI says you're not authenticated:

$ npx wrangler login

CLI: Resource Creation Fails​

  • Verify you're authenticated: npx wrangler whoami
  • Check your API token has the required permissions (see above)
  • Ensure you have available quota for the resource type

GitHub Actions: Workflow Fails​

  • Missing package-lock.json: The action requires both package.json and package-lock.json to be committed. If you see an error about missing package-lock.json, run npm install locally and commit both files.
  • Missing @package-broker/cloudflare: Ensure package.json includes @package-broker/cloudflare as a dependency. The template repository already includes this.
  • Verify all required secrets and variables are set
  • Check secret/variable names are exact (case-sensitive)
  • Review workflow logs for specific error messages
  • See SETUP.md for detailed troubleshooting

Database Migration Errors​

Migrations are applied automatically. If they fail:

# Check migration status
$ npx wrangler d1 migrations list <worker-name>-db --remote

# Manually re-run migrations if needed
$ npx wrangler d1 migrations apply <worker-name>-db --remote

Can't Access Dashboard​

  • Verify the Worker deployed successfully: npx wrangler deployments list
  • Check Worker logs: npx wrangler tail
  • Ensure you're using HTTPS (required for Workers)

Upgrading PACKAGE.broker​

CLI Method​

$ npm update @package-broker/cli @package-broker/main
$ npx wrangler deploy

GitHub Template Method​

Update package.json in your repository to bump dependency versions:

{
  "dependencies": {
    "@package-broker/main": "^0.9.0",
    "@package-broker/ui": "^0.9.0",
    "@package-broker/cloudflare": "^0.9.0"
  }
}

Then run npm install locally to update package-lock.json, commit both files, and push to main branch. The workflow will automatically deploy the new version.

Project Structure​

After initialization, your project structure will look like:

package-broker-deployment/
├── node_modules/
├── migrations/          # Database migration files (auto-copied)
├── wrangler.toml        # Cloudflare Workers configuration (auto-generated)
├── package.json
└── package-lock.json

Note: wrangler.toml does not contain ENCRYPTION_KEY - it's set as a Cloudflare secret.

Next Steps​