Build And Deploy A Connector Server
Deploy the connector server anywhere that can run Node.js and expose HTTPS. The generated template and this repository both use Express plus @app-connect/core.
Local Development
Install dependencies with npm ci in CI, or npm install locally when you intend to change dependencies, before building this repository. The root workspace lock is committed; .npmrc sets omit-lockfile-registry-resolved=true so it does not embed a registry URL. The repository template does not ship a development lock. Generated applications create their own lock during installation and may commit that application lock. The independent MCP UI retains its committed lock and uses npm ci.
Run the template server locally:
npm run dev
For this repository, run:
npm run start
Use a public HTTPS tunnel during Developer Console testing.
AWS Serverless Deployment
The repository includes serverless deployment folders such as serverless-deploy.
Typical flow:
cd serverless-deploy
cp sample.env.yml env.yml
cp sample.serverless.yml serverless.yml
Edit both files, then build and deploy from the project root:
npm run build
npm run deploy
Test/beta deployment variants are available through scripts such as build-test, deploy-test, build-test-beta, and deploy-test-beta.
Retain the production artifact's post-install lock and dependency inventory with its source revision and Node/npm versions for SCA and rollback. Root development locks are not committed, so an external scan job must resolve the current manifests or consume the generated, verified lock instead of reusing an old checkout snapshot. See dependency verification.
Heroku Deployment
The generated template doesn't include Heroku scaffolding out of the box (unlike the
azure-deploy and serverless-deploy folders), since the app already binds to
process.env.PORT, deploying to Heroku only needs a Procfile and a couple of config
vars — no code changes.
- Add a
Procfileto the project root:
web: npm run prod
- Create the app and set required config vars, including
APP_HOST=0.0.0.0— Heroku's router expects the dyno to bind to all interfaces, notlocalhost, and this is the most common cause of a connector failing its health check on first deploy:
heroku create <app-name>
heroku config:set APP_HOST=0.0.0.0
heroku config:set APP_SERVER=https://<app-name>.herokuapp.com
# ...plus APP_SERVER_SECRET_KEY, AC_DATABASE_URL, and any CRM OAuth variables
- Deploy with
git push heroku main, or connect the repo under the Heroku Dashboard's Deploy tab for automatic deploys from GitHub.
Deploying Elsewhere
If you deploy to another platform, build a local artifact:
npm run build-local
Deploy the generated build output according to your hosting provider.
Environment Variables
Common variables:
| Variable | Description |
|---|---|
APP_SERVER |
Public base URL for this connector server. |
APP_HOST |
Local host bind value for development. |
PORT |
Local server port. |
APP_SERVER_SECRET_KEY |
Shared secret used by the app server. |
AC_DATABASE_URL |
Preferred App Connect Sequelize database URL. Use sqlite:... for SQLite or postgres://... / postgresql://... for Postgres. |
DATABASE_URL |
Backward-compatible database URL. Used only when AC_DATABASE_URL is unset. |
DATABASE_SSL |
Optional Postgres SSL override. When unset, localhost database hosts use SSL off and other Postgres hosts use SSL on. |
DISABLE_SYNC_DB_TABLE |
Set when table sync should be skipped. |
DYNAMODB_LOCALHOST |
Local DynamoDB endpoint for local Dynamo-backed models. |
ERROR_REPORT_S3_BUCKET |
Error-report bucket for cloud storage, or an optional custom bucket in explicit local mode. |
ERROR_REPORT_S3_LOCAL |
Set to true to enable local MinIO/LocalStack report storage. An absent cloud bucket does not enable local storage. |
LOCALSTACK_ENDPOINT |
Optional endpoint for explicit local report storage, including container hostnames. |
MINIO_ROOT_USER, MINIO_ROOT_PASSWORD |
Credentials shared by the local MinIO process and local report storage. Both are required in local mode. |
DEVELOPER_DYNAMODB_TABLE_PREFIX |
Prefix for Developer Console connector/proxy DynamoDB tables. |
DEVELOPER_APP_SERVER_SECRET_KEY |
Secret used to decrypt stored connector secrets. |
| CRM OAuth variables | Connector-specific client IDs, client secrets, token URLs, and redirect URIs used by getOauthInfo(). |
RINGCENTRAL_SERVER, RINGCENTRAL_CLIENT_ID, RINGCENTRAL_CLIENT_SECRET |
Required for RingCentral admin OAuth and some reporting flows. |
RINGCENTRAL_MCP_CLIENT_ID |
Public RingCentral OAuth client ID used by MCP clients with PKCE. Do not use a client secret for MCP OAuth. |
Keep CRM client secrets and app secrets in environment variables, not in the manifest.
Before using local error-report uploads, enable local mode and supply the MinIO credentials in the same environment used by npm run s3-local. There is no embedded default account. Cloud mode uses the AWS credential provider chain and does not apply the local endpoint or credentials. Storage configuration is validated when first used, so an unused, unconfigured report feature does not prevent server startup; unavailable report storage returns a generic 503 response. Verification: packages/core/test/lib/s3ErrorLogConfig.test.ts and packages/core/test/routes/jsonResponseSecurity.test.ts.
Serverless builds MUST fail if dependency installation fails, and MUST NOT report successful completion or proceed to deployment with an incomplete dependency graph. Verification: tests/serverlessInstallFailure.unit.test.ts covers all root build variants and the generated-app build script.
For local Postgres, use a localhost URL so SSL is disabled automatically:
AC_DATABASE_URL=postgres://app_connect:password@localhost:5432/app_connect
For a remote Postgres host, SSL is enabled automatically. Set DATABASE_SSL=false only when a non-local database explicitly does not support SSL.
When both database URL variables are set, App Connect uses AC_DATABASE_URL and emits
a warning. Startup also reports the selected database target without exposing its
username, password, or query parameters.
Automating This Step
Connectors scaffolded with the appconnect-connector-skills Claude Code plugin get an
appconnect-deploy skill as the last step of a build. It asks where the connector will
be hosted (AWS, Azure, or Heroku), then removes the deploy scaffolding for the paths you
didn't pick — the template ships with both azure-deploy/ and serverless-deploy/ by
default — and for Heroku, which isn't in the template, writes the Procfile, app.json,
and setup instructions described above.
Deployment Checklist
- Public HTTPS server URL is configured in the Developer Console.
- The complete Developer Console Unique Identifier, including any developer namespace, exactly matches the server's
connectorRegistry.registerConnector()key. - Database and DynamoDB dependencies are reachable.
- Required CRM OAuth/API-key environment variables are set.
/isAlivereturnsOK./implementedInterfaces?platform=<complete-unique-identifier>returns HTTP 200 and reports expected methods.- OAuth redirect URIs in the CRM developer app match the values returned by
getOauthInfo.