Deployment

Prerequisites

Node.js 24 is required. All commands that invoke Node.js, npm, or wrangler must be run under nvm use 24.

source ~/.nvm/nvm.sh && nvm use 24

Build

The build step bundles frontend JavaScript via esbuild, copies HTML files from public/ to static/ (rewriting asset paths), builds documentation with docmd, and generates a help redirect page.

npm run build

This produces:

  • static/panel-bundle.js – deal sidebar panel
  • static/settings-bundle.js – settings page
  • static/field-modal-bundle.js – field comparison modal
  • static/docs/ – documentation site
  • static/*.html – HTML pages copied from public/

All build artifacts in static/ are gitignored.

Deploy

Production deployment is handled by Cloudflare Workers Builds from the connected GitHub repository. Local development should verify the build and tests, then push to origin/master; the push triggers Cloudflare to build and deploy the Worker.

npm run build
npm test
git push origin master

Do not use wrangler deploy locally as the normal deployment path. npm run deploy is intentionally disabled and exits with instructions to push to origin/master instead.

Configure Cloudflare Workers Builds with:

Setting Value
Root directory repository root
Production branch master
Build command npm run build
Deploy command npx wrangler deploy
Non-production branch deploy command npx wrangler versions upload

Cloudflare documents Workers Builds as a two-step process: an optional build command that compiles the project, followed by a deploy command that defaults to npx wrangler deploy. Non-production branch builds default to npx wrangler versions upload, which creates a preview version without promoting it to production.

Database Migrations

Migrations live in the migrations/ directory. Each new migration must be applied to production D1 before deploying the worker that depends on it:

source ~/.nvm/nvm.sh && nvm use 24
npx wrangler d1 execute pipedrive-utilities-db --remote --file=./migrations/<migration_file>.sql
npm run build
npm test
git push origin master

For local development, apply migrations with:

npx wrangler d1 execute pipedrive-utilities-db --local --file=./migrations/<migration_file>.sql

The db:migrate:local and db:migrate:remote npm scripts only run 0001_init.sql. For newer migrations, use the npx wrangler d1 execute command directly as shown above.

Secrets

The following secrets must be set via wrangler secret put <NAME>:

Secret Purpose
PIPEDRIVE_CLIENT_ID Pipedrive OAuth2 application client ID
PIPEDRIVE_CLIENT_SECRET Pipedrive OAuth2 application client secret
SESSION_SECRET Secret used to sign session cookies
CUSTOM_MODAL_ACTION_ID Pipedrive custom action ID for the field comparison modal
GOOGLE_ADS_DEVELOPER_TOKEN Google Ads API developer token
GOOGLE_ADS_CLIENT_ID Google Ads OAuth2 client ID
GOOGLE_ADS_CLIENT_SECRET Google Ads OAuth2 client secret

Environment Variables

Defined in wrangler.toml under [vars]:

Variable Purpose
BASE_URL Canonical public URL of the deployed worker, without a trailing slash: https://pipedrive-utilities.sessions.edu. This must match the production custom domain because it is used for OAuth redirect URIs and callback links.

Custom Domain Changes

When moving the Panel from the default workers.dev hostname to a custom domain:

  1. Attach the custom domain or route to the pipedrive-utilities Worker in Cloudflare.
  2. Update BASE_URL in wrangler.toml to the custom domain: https://pipedrive-utilities.sessions.edu.
  3. Update the Pipedrive app’s custom UI iframe URLs:
    • /panel
    • /settings
    • /field-modal
  4. Update the Pipedrive app’s OAuth redirect URL to:
    • /auth/callback on the same custom domain.
  5. Confirm Cloudflare Workers Builds is still deploying the same Worker name from wrangler.toml.
  6. Push the change to origin/master; Cloudflare will build and deploy it.

The app also builds links to /docs/, /settings, /panel, /field-modal, and /portal-request as same-origin paths, so no code change is normally needed for those routes beyond setting the canonical BASE_URL and updating the Pipedrive developer configuration.

Wrangler Bindings

Binding Type Description
DB D1 Database Cloudflare D1 database (pipedrive-utilities-db)
ASSETS Static Assets Serves files from ./static
Previous API Reference Next Database Schema