heroku-buildpack-datomic

by opengrail

GitHub Readme.md

Heroku buildpack to start a Datomic Transactor

What this buildpack does

  • obtains and packages Datomic

  • prepares Datomic storage configurations

  • starts the Datomic transactor

The rest of this README explains the necessary configuration.

Heroku pre-requisites (not free!)

This technology exploits the features of Heroku Spaces to securely inter-connect dynos.

To use this buildpack you need to have access to Heroku Spaces. Outside of Heroku Spaces, Datomic security is not assured.

Please check out an associated blog post providing more background

Configuring a custom buildpack

To enable this buildpack on an existing project:

heroku buildpacks:set https://github.com/opengrail/heroku-buildpack-datomic -a myapp

For more options and information see the Heroku web site on third party buildpacks

Detection

The buildpack will detect that you wish to start a Datomic transactor if your project has a Procfile in its top level directory that has this line:

datomic: /app/scripts/start-datomic.sh

Configuration

Datomic free configuration - playtime only!!

By default Datomic free will be started. Data will not be stored between startups

By default the version of Datomic is the latest published version with 0.9.5344 as a fallback if the latest version cannot be detected for some reason.

You can also configure the version of Datomic you wish to deploy.

heroku config:set DATOMIC_VERSION=version-number

Datomic Pro configuration

You can get a copy of the Datomic Pro starter edition which is free for 12 months or bring your supported license.

heroku config:set DATOMIC_LICENSE_PASSWORD=license-password

heroku config:set DATOMIC_LICENSE_USER=license-user

heroku config:set DATOMIC_TRANSACTOR_KEY=license-key

By default the version of Datomic is the latest published version with 0.9.5344 as a fallback if the latest version cannot be detected for some reason.

You can optionally configure the version of Datomic you wish to deploy.

heroku config:set DATOMIC_VERSION=version-number

Storage options

The buildpack has support for Heroku Postgres and Amazon DynamoDB

heroku config:set DATOMIC_STORAGE_TYPE=storage_type

where storage_type is HEROKU_POSTGRES or DYNAMODB.

By default the buildpack will try to configure for HEROKU_POSTGRES

Heroku Postgres - Pro editions only

The only Postgres database supported is Heroku Postgres (free or paid)

This buildpack will automatically configure Postgres for use with Datomic (if not already done)

Amazon DynamoDB - Pro editions only

We aim for simplicity in this buildpack so we reuse the defaults for DynamoDB that Datomic supports.

This buildpack will check that DynamoDB is configured for use with Datomic using the automated setup that Datomic provides.

To provide your Amazon account details to Heroku set the configuration variables for your app like this:

heroku config:set AWS_ACCESS_KEY_ID=aws-access-key-id AWS_SECRET_KEY=aws-secret-key

Dyno size

The buildpack defaults to 2Gb RAM. In production, 4Gb or more is preferred. See Datomic documentation on capacity planning.

Dyno count - theoretical

I have not proven this failover so you will need to work with Cognitect to obtain proper assurances

In theory, to manage failover for the Pro edition (not starter or free), 2 transactor workers can be started.

heroku ps:scale datomic=2

Consult the Datomic High Availability documentation for more details.

ToDo

  • Enable further configuration such as JVM memory

  • support other SQL DBs [ postgres and Oracle on Amazon RDS, MySQL Heroku addons (cleardb and jawsdb) ]

  • support cassandra via Heroku addon (Instaclustr)

Basis

This is forked from the official Heroku buildpack for Java apps.

Contributors

Thanks to the following GitHub users for providing PRs

License

Licensed under the MIT License. See LICENSE file.