aer-buildpack

Heroku buildpack for Salesforce projects that runs aer server with the source directory.

Usage

Add this buildpack to your Heroku app:

heroku buildpacks:set https://github.com/octoberswimmer/aer-buildpack

Or specify it in app.json:

{
  "buildpacks": [
    {
      "url": "https://github.com/octoberswimmer/aer-buildpack"
    }
  ]
}

Detection

This buildpack detects Salesforce projects by looking for sfdx-project.json in the root directory.

Configuration

AER_VERSION

Set the AER_VERSION config var to specify a particular version of aer:

heroku config:set AER_VERSION=v1.0.0

If not set, the latest release will be used.

AER_LICENSE_KEY

Set the AER_LICENSE_KEY config var with your license key:

heroku config:set AER_LICENSE_KEY=your-license-key

AER_PASSWORD

Warning: The server will be publicly accessible unless you set a password.

Set the AER_PASSWORD config var to require authentication:

heroku config:set AER_PASSWORD=your-password

Source Directories

The buildpack reads sfdx-project.json the same way the aer sf plugin does:

• Every path in the packageDirectories array is served, in order.
• Each package directory's unpackagedMetadata.path is served as well, so metadata that the packaged source depends on is available.
• If the project has a namespace, it is passed to the server as --default-namespace.
• Permission sets named in each package directory's apexTestAccess.permissionSets are assigned to the default admin user via --assign-perms (deduped, in first-seen order). apexTestAccess.permissionSetLicenses have no aer equivalent and are ignored, with a warning during the build.

If no package directories are found, the source directory defaults to force-app.

Replacements

The buildpack supports the replacements property of sfdx-project.json (string replacements), with the same semantics as the aer sf plugin and sf project deploy start: files are matched by filename or glob, gated on replaceWhenEnv conditions, and rewritten with replaceWithEnv or replaceWithFile values. Binary files are never modified.

Replacements run at dyno startup, not at build time, so changing a config var with heroku config:set takes effect on the next restart. At build time, the buildpack matches replacements against the project's source files and resolves replaceWithFile values; at startup a small Perl script applies the replacements using the dyno's current environment.

If a replaceWithEnv variable is unset (and allowUnsetEnvVariable is not set), the dyno fails to start with an error in the logs rather than running with placeholder values.

Default Process

The buildpack configures the default web process as:

web: aer server <source-directories...> [--default-namespace <namespace>] [--assign-perms <permission-set>...]