Deploying an Aqueduct Application on Heroku
For other deployment options, see Deploying Aqueduct Applications.
To run a production Aqueduct application on Heroku. Make sure to also read Testing Aqueduct Applications.
- Dart has been installed.
- A Heroku account.
githas been installed.
herokuhas been installed.
- Aqueduct has been activated.
- Setting up a Heroku application
- Setting up an Aqueduct application to run on Heroku
- Configuring application values
- Running the Aqueduct application
Estimated Time: 5 minutes.
Step 1: Setting up a Heroku Application
Create a new application in Heroku's web portal, and if you are using a database, add the 'Heroku Postgres' add-on.
Navigate to the Settings tab in the Heroku web interface and click 'Reveal Config Vars'. Note that there is a DATABASE_URL environment variable that is the connection details for your PostgreSQL database. You won't need to remember the value, only that this environment variable exists.
Step 2: Setting up an Aqueduct Application to Run on Heroku
If you have not yet, create a new Aqueduct application on your local machine, go into that directory, and initialize it as a git repository if it is not already:
aqueduct create app_name
Run the following commands to configure your project in Heroku's environment.
Heroku Application Name
In the following commands, ensure that
app_name is the name of your Heroku application created in their web portal, not the name of your Aqueduct application.
# This is an interactive command that you have to enter your username and password.
# This adds a remote repository hosted by Heroku for your application that you push to.
heroku git:remote -a app_name
# Specifies the Dart SDK to use
heroku config:set DART_SDK_URL=https://storage.googleapis.com/dart-archive/channels/stable/release/latest/sdk/dartsdk-linux-x64-release.zip
# Specifies the Heroku Buildpack to use
heroku config:set BUILDPACK_URL=https://github.com/stablekernel/heroku-buildpack-dart.git
# Specifies that aqueduct should be activated
heroku config:set DART_GLOBAL_PACKAGES="[email protected]"
heroku config:set PATH=/app/bin:/usr/local/bin:/usr/bin:/bin:/app/.pub-cache/bin:/app/dart-sdk/bin
heroku config:set PUB_CACHE=/app/pub-cache
Then, create a new file in your project directory named
Procfile (with no suffix) and enter the following:
release: /app/dart-sdk/bin/pub global run aqueduct:aqueduct db upgrade --connect $DATABASE_URL
web: /app/dart-sdk/bin/pub global run aqueduct:aqueduct serve --port $PORT --config-path heroku.yaml
This file tells Heroku how to run your application, and to execute any database migrations each time you push a release. Make sure this file is checked into version control:
git commit -am "Adds Procfile"
Step 3: Configuring Application Values
Heroku provides configuration values through environment variables. In our
Procfile, we indicated that we will use a file named
heroku.yaml for configuration. This file will map configuration values in our application to environment variables in the Heroku platform. Your configuration file may vary, but it is important to note that if you are using a database, the database credentials are provided through a
connection string. A connection string looks like this:
postgres://user:password@host:5432/name and by default, Heroku stores it in the environment variable named
heroku.yaml (which you will need to create in your project directory), you can reference an environment variable by prefixing its name with a
$. When using the built-in
DatabaseConfiguration type, you can assign the connection string like so:
Your heroku.yaml might be different
Make sure the structure of your
heroku.yaml file matches the expected structure in your application's
heroku.yaml into version control.
git commit -am "add heroku.yaml"
Step 4: Running the Aqueduct Application
If your application uses a database, make sure you have generated your migration file(s) and added it to version control. The
Procfile will ensure that database is up to date with any migrations checked into source control before running your app. Generate your migration file with the following command from your project directory and then check it into version control:
aqueduct db generate
git commit -am "adds migration files"
Now, you can deploy your application. It's as simple as this:
git push heroku master
This command pushes your code to a remote git server hosted by Heroku, which triggers your application to run its release script.
Now that your application's database schema has been uploaded, you can configure your OAuth 2 server with client identifiers if you are using
package:aqueduct/managed_auth. The following command will run within your application's remote environment.
heroku run /app/dart-sdk/bin/pub global run aqueduct:aqueduct auth add-client --id com.app.standard --secret secret --connect \$DATABASE_URL
Finally, scale up a dyno and the application will start receiving requests:
heroku ps:scale web=1
Now your application is running!