heroku.md

Heroku

{% hint style="danger" %} Amber 0.7.2 isn't compatible with Crystal 0.25.0

Please use a .crystal-version file with 0.24.2 instead {% endhint %}

If you haven't done so please read the guides to install the Amber CLI

The Amber Heroku Buildpack

{% hint style="info" %} Based on Crystal Heroku Buildpack {% endhint %}

You can create an app in Heroku with Amber buildpack by running the following command:

$ heroku create myapp --buildpack https://github.com/amberframework/heroku-buildpack-amber.git
$ heroku buildpacks:add --index 2 heroku/nodejs # To build default assets

The default behaviour is to use the latest crystal release. If you need to use a specific version create a .crystal-version file in your application root directory with the version that should be used (e.g. 0.23.1).

Requirements

First of all you need to add Heroku addons: Heroku Redis and Heroku Postgres for created app. Then uncomment in config/settings.cr:

settings.redis_url = ENV["REDIS_URL"] if ENV["REDIS_URL"]?

settings.database_url = ENV["DATABASE_URL"] if ENV["DATABASE_URL"]?

In order for the buildpack to work properly you should have a shard.yml file,as it is how it will detect that your app is a Crystal app. Your application has to listen on a port defined by Heroku.

{% hint style="warning" %} In Amber versions less than or equal to 0.3.7 add the following code to your config/application.cr file {% endhint %}

Amber::Server.configure do |settings|
  settings.host = "0.0.0.0"
  settings.port = ENV["PORT"].to_i if ENV["PORT"]?
end

To be able to decrypt and use production environment you'll need to set ENV["AMBER_ENCRYPTION_KEY"] to the value of your local projects .encryption_key file.

{% hint style="danger" %} Never add .encryption_key to github. Amber adds it by default to your .gitignore file. {% endhint %}

All that's left is to create a git repository, add the Heroku remote and push it there.

$ git init
$ heroku git:remote -a [app-name]
$ git add -A
$ git commit -m "My first Amber app"
$ git push heroku master

Using the Amber CLI on Heroku

When you deploy your project to heroku the amber build-pack will make available the amber cli to you via the bin/amber path.

To run an amber command just on heroku do the following:

heroku run bin/amber [command]

{% hint style="info" %} Read more about heroku run command on Heroku Dev Center {% endhint %}

The Heroku Procfile

To deploy your app to heroku you're going to need a Procfile. Create a Procfile at the root of your Amber application and add the following:

release: bin/amber db migrate
web: bin/{your-app-name}

The Amber buildpack takes care of compiling the project for you but if you wish to run your project locally using the heroku command heroku local you must do the following steps.

Create an .env at the root of your Amber project and add the following 2 lines to the .env

AMBER_ENV=development
PORT=3000

Then you must compile your project locally with the following command:

crystal build src/{your-app-name}.cr -o bin/{your-app-name}.

When the compilation process is complete a bin/{your-app-name} directory is added, with this binary of your application with this binary file ready you can proceed to run your application locally with heroku.

heroku local

And should output something similar to:

[OKAY] Loaded ENV .env File as KEY=VALUE Format
02:58:31 web.1   | 02:58:31 Server     | (INFO) Amber 0.7.2 serving application "heroku-app" at http://0.0.0.0:3000
02:58:31 web.1   | 02:58:31 Server     | (INFO) Server started in production.
02:58:31 web.1   | 02:58:31 Server     | (INFO) Startup Time 00:00:00.000182000

You're are now all set and ready to deploy with Heroku.