Guide: Getting Setup
This guide is maintained at https://github.com/muoncore/guide Please submit issues at that repository. |
Today, you will
-
get a development environment setup, including the cli
-
See some helper services we provide to make things easier
-
build a couple of microservices
-
have them do something useful
Unresolved directive in index.adoc - include::guide/1-setup/../12daypromo.adoc[]
Setting up your Environment
Muon is not demanding of you development environment. You can use your regular IDE, and your language and frameworks of choice, so long as the language runtime is currently supported.
One thing that is necessary is support for the network transport that Muon services will use to communicate with each other.
Currently, AMQP is best supported, and so that is what we will use.
Aside from that, you don’t need anything else to develop Muon services.
That said, we provide a set of Microservices that give a set of basic functionality that we find is often wanted.
These are (as of writing):-
-
Photon - an Event Store and Projection engine
-
Molecule - a pluggable React based UI
These, along with RabbitMQ, give the base environment we recommend for you to get started developing Muon services.
We provide two main routes to get them, a Docker Compose environment, and a Vagrant VM that wraps the Docker Compose environment.
Installing the Base Services using Docker Compose
Go to https://github.com/muoncore/muon-starter and follow the instructions there.
once complete, you will have the services running, you can check them with the CLI (installed below) or by visiting the Molecule UI at http://localhost:3420
Installing the Base Services using Vagrant
This is awaiting a stable vagrant build
Installing the CLI
Muon provides a CLI. You install this using npm, from the Node.js environment.
You do not need to code in JavaScript or use node beyond this if you don’t want to, but it is currently required to use the CLI.
Install NPM (as at https://www.npmjs.com/)
Then install muon using
> npm install -g muon-cli
Check it’s working using the discover
commmand, or it’s short version d
. This will list
all of the currently running Muon services.
You will need to set the MUON_URL environment variable first, which tells Muon how to connect to the network transport/ discovery service. In this case, RabbitMQ
> export MUON_URL=amqp://muon:microservices@localhost
> muon d
Once this works, you have a running CLI, and you can begin to interrogate what the services can do.
Likely, you only have Photon and Molecule running.
Let’s build some more!
Building a multi protocol API
We are building a Pie shop management system. We will start designing and building proper services in the next section. Today though, we just want to get something running.
Often, the easiest way to get started with a system is to define the queries that you need to make. Without concerning yourself with changing data, we can effectively stub out the data we want to provide.
With Muon, we have the opportunity to incorporate multiple different protocols to make our API.
Built in, we can use RPC for simple request/ response, and Reactive Streaming, for streaming push updates.
For this API, we will build an API for the Menu.
This will be ultimately be made available on the web, on tabletop displays and wait staff mobile devices (although we won’t build a mobile app in this tutorial!)
In this case, the data set is small, and so instead of providing granular APIs, we will request the entire data set and process it in local memory to get the best performance and tolerate network failure.
We will provide two endpoints, one RPC and the other Stream. This will allow clients to get the current state, and also receive push updates whenever we update the menu data
Muon Java Microservice
The Menu service, we will write in Java. To get started wth this, download Gradle.
Try using SDKMan
Create the build file
Create a new Gradle build file as below.
buildscript { ext { springBootVersion = '1.4.2.RELEASE' (1) } repositories { mavenCentral() } dependencies { classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}") } } apply plugin: 'java' apply plugin: 'org.springframework.boot' sourceCompatibility = 1.8 version = '1.0' springBoot { mainClass = 'pieshop.Menu' (2) } repositories { jcenter() maven { url 'https://simplicityitself.artifactoryonline.com/simplicityitself/muon' } (3) } dependencies { def muonVersion = "7.1.3" (4) compile "io.muoncore:muon-core:$muonVersion" compile "io.muoncore:muon-transport-amqp:$muonVersion" compile "io.muoncore:muon-discovery-amqp:$muonVersion" compile 'io.reactivex.rxjava2:rxjava:2.0.3' (5) } task wrapper(type: Wrapper) { gradleVersion = '3.2.1' }
1 | We use the Spring Boot gradle plugin to give us easy uberjar and app distribution |
2 | Set the main class for the spring boot plugin run command |
3 | Add the Artifactory url where the muon libraries can be found |
4 | The latest version of Muon, with the basic libraries for connecting to AMQP. |
5 | The current version of RxJava, which we will use to build a streaming endpoint |
Create the standard file structure
src/ main/ java/
Create Muon Service class
To start with, we need a single class to put our Muon API in. Later in the series we will separate them up.
Create the class referenced above pieshop.Menu
as a regular Java class with a Main method.
like this
package pieshop;
import io.muoncore.Muon;
import io.muoncore.MuonBuilder;
import io.muoncore.config.AutoConfiguration;
import io.muoncore.config.MuonConfigBuilder;
import io.muoncore.protocol.reactivestream.server.PublisherLookup;
import io.reactivex.Flowable;
import static io.muoncore.protocol.requestresponse.server.HandlerPredicates.all;
public class Menu {
public static void main(String[] args) {
AutoConfiguration config =
MuonConfigBuilder.withServiceIdentifier( (1)
"menu").build();
Muon muon = MuonBuilder.withConfig(config).build(); (2)
muon.handleRequest(all(), request -> { (3)
request.ok("hello world");
});
muon.publishSource( (4)
"mysource",
PublisherLookup.PublisherType.HOT,
Flowable.just("Hello", "World", "Item")); (5)
}
}
1 | Construct a configuration for Muon. Here using all the defaults and call the service menu |
2 | Using the configuration, build a running Muon instance |
3 | Create an RPC protocol request handler. This uses all() , which matches any incoming request |
4 | Create a new reactive streaming endpoint named mysource |
5 | Use an RxJava2 as the source for the endpoint. |
This can be run using the bootRun
command from the Spring Boot Gradle plugin
> gradle bootRun
You can then make a request to the service using the CLI and recieve hello world
in return
> muon rpc rpc://menu/
You can subscribe to the stream endpoint like so
> muon stream stream://menu/mysource 'Hello' 'World' 'Item'
The subscription will request and print all items, then when the source Flowable
sends the complete signal,
the cli will cleanly exit.
Summary
You now have a Muon environment ready to build services with. You will be building lots of them.
In the next episode of the series, you will:
-
Create a set of microservices that form the API of the shop.
-
Understand how to use the two protocols above to service the data in different forms.