Thomas Allerton
Apr 12 · 4 min read

Have you ever spent far too many hours trying to set up your cloud deployment, be that with the serverless framework, or with dreaded CloudFormation? Me too.

From silly things like forgetting my language runtime parameter, to in deep with other resources and permissions, there was always something not quite right. Even once I had a deployment up and running I usually found that my code would fail for one reason or another, like permissions or using the wrong Lambda input type. Each of these issues then leads to sitting around and waiting while you upload your code, again and again, until finally, you stumble into what the cloud provider expects from you.

For newcomers looking to make simple applications, there can be a very steep learning curve, having to learn the cloud lingo when all you really want is to deploy a few HTTP endpoints with somewhere to store the data. Even experienced users are prone to making very simple mistakes that can take a long time to fix, depending on how late in the deployment process an error message is spat out at you. This is where Nimbus comes in, a new Java framework that allows you to declare your cloud resources and functions using annotations, as well as providing built-in clients that allow for much easier interfacing with the resources.

The main advantage of Nimbus is that you do not have to create a configuration file to declare your cloud resources, and so are much less prone to making mistakes by forgetting parameters. Additionally, Nimbus does compile-time checking of your deployment parameters to help catch any mistakes you may have made.

For a faster testing cycle, Nimbus allows you deploy your code locally, in a small scale fashion designed for unit tests, or in a larger scale with locally running web servers that can be interacted with.

Finally, Nimbus provides a much easier interface to work with cloud resources, in a cloud-agnostic fashion. It should be noted that these provide slightly less functionality than the cloud providers own interfaces in some cases, but should provide all the functionality required for most use cases. If not then the cloud provider’s implementation is still available.


So let’s start with an example. First, the right dependencies need to be added to your maven pom file. There are 3 things that needed to be added.

  1. The nimbus-core dependency, for the annotation processor.
  2. The nimbus-deployment-maven-plugin, to handle the deployments.
  3. The maven shade plugin to create a shaded jar with all the function dependencies to upload to the cloud provider.

Here is a complete pom example, configured for AWS:

The region parameter specifies what AWS region you’ll want to deploy to.

Now onto some code. Say we want to create a REST API that allows users to create and query events, where the events have some unique id and a number of people interested in them. Here is our very simple Event object:

Note the @DocumentStore annotation as well as the @Key and @Attribute annotations. These create for us a table which will store Event objects, which will be accessed based on the key. It is important that it has an empty constructor available for deserialization purposes.

Now for the API, we want an endpoint to create events, an endpoint to get events, and an endpoint to register someone as interested in the event. This can be done like so:

Here we declare our endpoints using the @HttpServerlessFunction annotation, supplying a path and HTTP method.

And that’s all the code we need! All we need to do now is deploy to the environment. Currently, only AWS is supported, so in order to deploy, you’ll need to supply your AWS credentials, see here for details. Now you just need to build your code by running mvn package and then deploy by running mvn nimbus-deployment:deploy .

And that’s it! A very simple example of powerful things Nimbus can do. Compared to the serverless framework, no large configuration file was needed or any AWS specific code. In the future, more cloud providers are planned so that it will be very easy to migrate your code.


Another major feature of Nimbus is allowing you to write unit tests and run your code locally. With the above example in mind, we could check that the newEvent method does add the correct item to the table.

This test first creates a new local deployment, then as a sanity check makes sure the event store is empty. We then send an HTTP request via the local deployment (as this means we don’t have to start up a full HTTP server) and then check that the new event has appeared in the store. Creating unit tests like this one also allow Nimbus to check common runtime errors, like forgetting to add an @UsesResource type of annotation.

If you want to create a local server then you can do:

This will create a full local HTTP server, as well as a WebSocket server if you are using those. This can then interact with any clients you have running locally.


Here is a brief list of some of the major cloud resources Nimbus supports:

  • HTTP, WebSocket, notification and queue function endpoints
  • Document and Key-Value stores.
  • Relational Databases
  • File Storage buckets, with static website compatibility

For more details of everything Nimbus supports, check out the documentation and guides on the website.

Please feel free to ask any questions here, or on the GitHub repository.

Check out my newest story where I show how to use Nimbus to make a chat application using WebSockets.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade