BLOG

Managing private Composer packages usually involves either paying for Private Packagist or maintaining a self-hosted instance of Satis. While Satis is great, it often requires a dedicated server and can be cumbersome to secure and maintain. Enter PACKAGE.broker.

What is PACKAGE.broker?

PACKAGE.broker is a self-hosted server application that acts as a proxy and cache for Composer packages. It sits between your PHP applications and upstream package sources (like GitHub, GitLab, or Bitbucket).

It stands out from alternatives like Satis because of its Sales-Force style security and modern architecture:

• Security First: It uses AES-256-GCM to encrypt stored credentials and offers robust token-based authentication.
• Edge-Optimized: Designed to run on serverless edge networks like Cloudflare Workers, meaning zero maintenance of underlying servers.
• Cost-Effective: You can host it entirely on Cloudflare's free tier (D1 for database, R2 for storage, KV for cache).
• Minimalistic: It avoids bloat, focusing solely on efficient package proxying and caching.

Step-by-Step Installation on Cloudflare

Deploying PACKAGE.broker on Cloudflare Workers is straightforward. Here is how to get it running using the CLI method.

1. Prerequisites

Ensure you have Node.js 18+ installed and a Cloudflare account. You'll need to be authenticated with Cloudflare via the terminal:

npx wrangler login

2. Install and Initialize

Create a new project directory and initialize the necessary packages:

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

The CLI will create a `wrangler.toml` configuration file and copy migration files to a `migrations/` directory.

3. Configure Resources

You need to create the Cloudflare resources that PACKAGE.broker depends on (D1 Database, KV Namespace, and R2 Bucket). You can do this via the Wrangler CLI:

# Create Database
npx wrangler d1 create <your-worker-name>-db

# Create KV Namespace
npx wrangler kv namespace create <your-worker-name>-kv

# Create R2 Bucket
npx wrangler r2 bucket create <your-worker-name>-artifacts

4. Update Configuration

Edit your `wrangler.toml` file with the IDs returned from the previous step. It should look something like this:

name = "my-package-broker"
main = "node_modules/@package-broker/cloudflare/worker.js"
compatibility_date = "2024-04-05"

[[d1_databases]]
binding = "DB"
database_name = "<your-worker-name>-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

[[kv_namespaces]]
binding = "KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "<your-worker-name>-artifacts"

5. Set Encryption Key

Generate a secure random key and set it as a secret in Cloudflare. This key is used to encrypt your Git credentials.

# Generate key
openssl rand -base64 32

# Set secret (paste key when prompted)
npx wrangler secret put ENCRYPTION_KEY

6. Deploy

Finally, apply the database migrations and deploy your worker:

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

7. Final Setup

Once deployed, open your Worker URL. You will be greeted with a setup screen to create your admin account. After logging in, you can create access tokens and start adding your private repository sources.

You now have a private, secure, serverless Composer repository running at the edge!