Gradle 5.0 or later (tested with 5.4.1).

Osiris includes two Gradle plugins. The first plugin is only used to generate a new project. The other plugin builds the project artifacts, generates the configuration files and deploys the application to AWS.

To create a project, open a terminal and create a new directory for the project:

mkdir my-app

Change into the directory:

cd my-app

Download the file generateProject.gradle and copy it into the directory.

If you have curl installed you can download it with this command:

curl -O https://raw.githubusercontent.com/cjkent/osiris/v1.6.0/gradle-plugin/src/main/gradle/generateProject.gradle

Run Gradle to create the project. You must specify the root package of the project as an argument. In the following example, replace com.example.app with your project package:

gradle -b generateProject.gradle -Ppackage=com.example.app

After creating the project you can delete generateProject.gradle.

The generated project contains two modules: core and local-server.

The core module contains the code that is deployed to AWS. It contains a file ApiDefinition.kt that defines an example REST API. This demonstrates many of the features of Osiris and is a useful place to start when learning how to use it.

All dependencies of the core module are included in the jar that is uploaded to AWS.

The local-server module contains the code and dependencies needed to run the application on a local machine. In contains a file Main.kt with a main function that starts a local Jetty server that serves the application.

The local server code is in a separate module to avoid uploading Jetty and all its dependencies to AWS.

Before deploying the project, ensure your AWS credentials are configured and the necessary environment variables are set. See here for details.

Run Gradle to deploy the project:

gradle deploy

This builds the project and deploys the application to AWS. You should see output ending with something like this:

> Task :gradle-app-core:deploy
Deployed to stage 'dev' at https://lk9fp61wc8.execute-api.eu-west-1.amazonaws.com/dev/
Deployed to stage 'prod' at https://lk9fp61wc8.execute-api.eu-west-1.amazonaws.com/prod/

BUILD SUCCESSFUL in 52s
8 actionable tasks: 7 executed, 1 up-to-date

The project is now deployed to AWS and available via a public URL. Enter the following command in the terminal to open a browser pointing at the application:

gradle open -b core/build.gradle -Pstage=dev -Pendpoint=/helloworld

You should see a JSON object { “message”: “hello, world!” } in the browser.

The deployment process uses AWS CloudFormation to define the resources needed by the API as a single, atomic unit (known as a CloudFormation "stack"). The resources should not be edited or deleted individually using the AWS consoles for the resources (for example the API Gateway console or the Lambda console). This will confuse CloudFormation and cause subsequent updates to fail.

When any of the code has changed, run gradle deploy again and the changes will be deployed.

The whole application can be deleted in a single operation via the CloudFormation console. Delete the stack whose name is the same as the project name.

The application can also be run in a local server. Running the local server in an IDE allows easy debugging and a faster development cycle than deploying changes to AWS. The local server is only intended for development and testing as it has no support for authentication and authorisation.

To run the server, run the main function in Main.kt in the local-server module.