Skip to main content

Quickstart: Cloudflare

Run one broker for your agency on Cloudflare Workers, then install one private Composer package through it. You can evaluate alone with a local administrator account.

What you need​

  • Git, Node.js 24 or later, and pnpm 12.5.1. Install these before starting; .nvmrc selects Node.js 24.

  • PHP compatible with your package and Composer 2 on the machine where you will install it. Composer 1 is refused.

  • A Cloudflare account with Workers Paid, Queues, R2 and Analytics Engine enabled, and an account Workers subdomain already registered in the dashboard. Setup checks service availability; it does not enable billing or register that subdomain.

  • An account API token scoped to the account you will use. The required account permissions, derived from the endpoints the CLI calls, are Workers Scripts Edit, D1 Edit, Workers R2 Storage Edit, Queues Edit and Account Analytics Read. Billing Read is optional. This recipe uses the account Workers address and does not need custom-domain or zone permissions.

  • A private Composer vendor repository containing a package you can install, its credentials, your administrator e-mail address, an authenticator app and a safe place to retain the generated master key.

Get the code​

Run these commands in a terminal on your trusted workstation:

git clone https://github.com/package-broker/broker.git
cd broker
pnpm install --frozen-lockfile
pnpm build

The repository runs its built CLI as pnpm pb; a global pb installation is unnecessary.

Deploy the broker​

In a Bash terminal with command tracing disabled, set CLOUDFLARE_ACCOUNT_ID to the 32-hex account ID from the Cloudflare dashboard. Replace <account-id> below with that ID. Run read, paste the API token at the hidden prompt and press Enter; the token is neither echoed nor entered in shell history. Do not put it in command arguments or the checkout. Run setup in the same interactive terminal:

export CLOUDFLARE_ACCOUNT_ID='<account-id>'
read -rs -p 'Cloudflare API token: ' CLOUDFLARE_API_TOKEN
printf '\n'
export CLOUDFLARE_API_TOKEN
pnpm pb cloudflare setup
unset CLOUDFLARE_API_TOKEN

Answer the prompts below; the prompt text is quoted verbatim:

PromptAnswer for this evaluation
workerName:A lowercase slug, such as broker.
orgSlug:A lowercase slug, such as agency.
orgName:Your organization name.
adminEmail:Your administrator e-mail address.
Environment [production]:Press Enter for production.
Deployment ID [worker-environment]:Press Enter for the suggested deployment ID.
Jurisdiction [eu/default; default eu]:Press Enter for eu; choose default only if that is your intended storage placement.
Optional creation location hint [none]:Leave blank.
Canonical HTTPS origin [workers.dev]:Leave blank to use the account Workers address.
Optional custom domain [none]:Leave blank.
Master key delivery [terminal/key-file/env; default terminal]:Choose key-file.
Key file outside the checkout:An unused absolute path in an existing private directory outside the checkout, such as <private-directory>/broker-master-key.

Setup creates the key file with mode 0600. Alternatively, terminal delivery reveals the key once and asks you to re-enter its last six characters without echoing them. The env option prompts Saved master key environment variable: and reads an already saved key from that named variable. Retain the key in a secret manager; losing it prevents recovery of encrypted credentials. After verifying that storage, delete the local key file.

Review the resource plan and type yes when asked. Setup builds the Worker, provisions D1, an R2 bucket, a jobs queue and a dead-letter queue, applies migrations, creates the organization, uploads the master key as a Worker secret, deploys the Worker with its UI assets and Analytics Engine binding, runs readiness and unauthenticated registry checks, and issues the first administrator's setup token. It does not yet test an authenticated package install; you do that below.

Success prints a JSON result with status: "ok", worker_url, bootstrap_url, resource identifiers and smoke checks. The setup token is delivered separately to the terminal, never embedded in the URL. Keep the private .pb/state/cloudflare inventory for safe reruns and recovery. If delivery is lost, rerun the same setup with --refresh-setup-token to request a replacement; this invalidates the previous unused token and cannot reset an enrolled login.

For unattended setup, the CLI also supports --worker-name, --org-slug, --org-name, --admin-email, --non-interactive, --yes, --key-file (or --master-key-env) and --token-file. Noninteractive first setup requires explicit key delivery and a token output file; use distinct unused paths outside the checkout. Preserve the same deployment identity on reruns.

Read Workers fill limits and self-origin aliases before importing a large catalog or adding a custom domain alongside the account Workers alias; it explains metadata sizing, D1 invocation budgets and the required outbound deny entries.

First administrator​

Open the returned bootstrap_url and use the separately delivered setup token to enroll your password and authenticator. The token expires after 24 hours and works once. Follow Set up the first administrator for the browser steps or the curl alternative, then return here signed in.

First project, source and token​

Use the returned worker_url as <broker-origin>. Open <broker-origin>/_pb/ui and sign in as the administrator. Use the scope selector to choose the organization, then open Projects. Under New project, enter a name and a lowercase slug such as evaluation, leave the token policy defaults, and choose Create project. Copy the project ID for token creation; <project> below means the slug.

  1. In organization scope, open Sources and create a source with Add source, ecosystem composer, source type Composer repository, a source name and the vendor repository's HTTPS URL, for example https://vendor.example.com. Enter the exact private package name in Package names (one per line) and set Sync interval (seconds), for example 300. Leave additional archive hosts empty unless the vendor serves archives from a separate host you trust with its credentials.

  2. Save the source. In Set credential, choose http_basic, enter the vendor's username and password, and choose Save credential. For a vendor that uses bearer authentication, choose bearer and enter its token instead. Store vendor credentials here, separately from the broker token Composer will use.

  3. Open More and choose Registered names. In the Registered names dialog, add the same exact package name with Add name, then close the dialog. Open More and choose Enable on the source. The package selection and registered names are separate settings; complete both.

  4. Still in organization scope, choose Sync now, then Refresh sources until the source reports a successful sync. Select your project in the scope selector, open Sources, find the organization source and choose Attach. Open Packages in project scope and check for the private package and a version you can install before continuing.

  5. Open Tokens, select My personal tokens, and expand Issue token. Enter a name, choose Read, choose a lifetime, select Selected projects, and paste the project ID into Selected project IDs (space separated; re-enter when renewing). Choose Issue token, complete reauthentication if requested, and confirm issuance. Save the complete pb_pat_ value when it appears; it is shown once. If asked for another authenticator code immediately after setup, wait for the next code.

Install a private package​

If you do not have an application yet, create an empty directory outside the broker checkout, open a terminal there, and use a local editor to create composer.json containing:

{
"name": "evaluation/application"
}

In your application's directory containing composer.json, replace <broker-host> with the broker host, including any port, <project> with your project slug, and <vendor>/<package> and <version> with the package and version you just checked. Vendor repositories must also supply any private dependencies you need; Packagist remains available for public packages.

composer config repositories.broker composer 'https://<broker-host>/<project>'

Add auth.json to your application's .gitignore. With a private local editor, create auth.json beside composer.json, replacing <personal-token> with the complete pb_pat_ token. Use the literal username token and key credentials by host and port, without the project path. Keep the file private and out of version control.

{
"http-basic": {
"<broker-host>": {
"username": "token",
"password": "<personal-token>"
}
}
}

Add the package, then verify an install from the resulting lock file:

composer require '<vendor>/<package>:<version>' --no-plugins --no-scripts
composer install --no-plugins --no-scripts

Check that composer.lock contains the private package and a distribution URL on your broker. These commands suppress package plugins and scripts; review your application's requirements before enabling them. For existing lock files and repository priority, follow the Composer guide. For JavaScript packages, see npm, pnpm and yarn; for automated installs, use GitHub Actions service tokens.

Sign-in for a team​

Team sign-in uses Cloudflare Access or an OpenID Connect provider such as Dex; grants to the provider's groups give users project access. Evaluating alone needs no identity provider: use the local administrator login. See the access model for group grants and token boundaries.

Next steps​

Plan backups and upgrades, review security and data residency, or migrate from Private Packagist, Satis or Packeton.