Documentation by ClonePartner

Start typing to search.

Deployment

Customer builds and catalog

View Markdown

Compile a customer-specific Envoy binary with envoy-builder, choose connector capabilities, and bundle catalog assets for boot-time registration.

Customer builds and catalog

Envoy compiles into a customer-specific standalone executable with a selected set of connectors and, when required, an approved connector catalog. This keeps the runtime self-contained and limits exposed capabilities to those intended for the deployment.

Build configuration is a release-engineering input, not an in-product connector configuration file.

Build configuration

Each customer has a YAML file in build/ (for example build/clonepartner.yaml):

name: clonepartner
include_server: true
branding:
  app_name: ClonePartner
  logo_url: /branding/clonepartner/logo.png
connections:
  - csv
  - yaml
  - sqlite
  - mongodb
  - truto
  - postgres
catalog:
  slugs:
    - stripe
    - hubspot
  out_dir: catalog/clonepartner
  • name — the binary and image name.
  • include_server — bundle the orchestration server and web UI.
  • connections — the connector types compiled into the binary.
  • catalog — optional file-mode catalog bundling: which integration slugs to package and where.

How the build works

bun scripts/envoy-builder.ts <customer> --all --out=dist

The builder reads the config, generates a registration entry file (the per-customer equivalent of src/register-all.ts) containing one registerConnector call per selected connector plus the metrics backends (noop, sqlite, statsd, http, mssql), then compiles standalone executables with Bun's compiler for the requested platforms (darwin-arm64, linux-x64, windows-x64). The full development registry in src/register-all.ts covers: azure-blob, csv, yaml, sqlite, truto, cardamom, mongodb, dynamics365, postgres, mysql, mssql, s3, jira, freshdesk.

The executable still receives environment-specific server configuration, secrets, database access, and Connector records at deployment time — nothing customer-account-specific is baked in.

Include every connector type referenced by a promoted bundle: Envoy rejects imported task definitions whose connector types are unavailable, and the validator reports Unknown connector type: '<type>'. Available: <list>.

Catalog connectors at boot

When a deployment configures a catalog — through the cardamom section of envoy-server.yaml or the ENVOY_CATALOG_INTEGRATIONS_DIR / ENVOY_CLOVE_URL environment variables — the server registers one connector type per catalog integration at startup (registerCatalogConnectors in src/connectors/catalog-connector.ts). Those types then appear in the Connector creation UI like any compiled-in type.

Two catalog sources exist:

  • File mode — a directory of integration JSON files packaged by the build (catalog.out_dir, mounted as /app/catalog/<customer>/ in Docker) and pointed at with integrations_dir.
  • Catalog service — a remote catalog reached through clove_url, which requires clove_token (clove_token is required when clove_url is set for catalog registration).

Registration can be disabled with cardamom.enabled: false. The config keys and their environment overrides are listed in Server configuration; connected-account behavior is documented in Catalog connectors and connected accounts.

Extending a deployment

To add capabilities to an existing deployment:

  • New compiled connector or step — requires a new build. Connectors extend BaseConnector and register in the build's entry file; steps extend BaseStep. Plan this as an application upgrade.
  • New catalog integration — for file-mode catalogs, ship updated catalog assets and restart; for a catalog service, publish the integration there. No recompilation is needed, because catalog types are registered at boot.

Keep catalog assets and runtime configuration separate. Catalog definitions describe available capabilities; Connector records identify a particular account with its non-secret settings and secret references. Never put customer credentials in build configuration, catalog definitions, compiled assets, task or job-template YAML, or release archives.

Verify a release

In a non-production environment:

  1. verify executable checksum and platform;
  2. start the control plane with a fresh test configuration;
  3. confirm the expected connector types appear and unapproved types do not;
  4. open the catalog-backed Connector forms and create a test Connector;
  5. run one paged discovery request;
  6. import representative Tasks with dry-run enabled;
  7. run a bounded end-to-end Job;
  8. record the release and catalog versions.

If a catalog path is mounted separately, verify the runtime account can read it and all executor instances receive the same version.

Upgrade planning

Treat a connector or catalog change as an application upgrade: review configuration-schema changes, verify renamed or removed methods, validate existing task definitions, test connected-account selection, and preserve a rollback artifact. Changing a catalog does not migrate stored Connector records — review existing configurations after an upgrade.