Getting started

On this page, you will go through :

Installing Microcks

Microcks may be installed in many ways depending your preferred environment. Basically, it can be installed on Kubernetes, on OpenShift, using Docker-Compose or directly using binary and source of Microcks.

Installing on Kubernetes

One easy way if installing Microcks is to do it on Kubernetes. Kubernetes in version 1.6 or greater is required. It is assumed that you have some kind of Kubernetes cluster up and running available. This can take several forms depending on your environment and needs :

  • Lightweight Minikube on your laptop, see Minikube project page,
  • Google Cloud Engine account in the cloud, see how to start a Free trial,
  • Any other Kubernetes distribution provider.
We provide basic Kubernetes manifest for simple needs but also a Chart for using with Helm Packet Manager. This is definitely the preferred way of installing apps on Kubernetes.
Just clone the GitHub repository, go to Helm directory and install the chart with these commands:
git clone https://github.com/microcks/microcks.git
cd microcks/install/kubernetes/helm
helm install ./microcks --name microcks --namespace=microcks

After some minutes and components have been deployed, you should end up with a Spring-boot Pod, a MongoDB Pod, a Postman-runtime Pod, a Keycloak Pod and a PostgreSQL Pod like in the screenshot below.

Now you can retrieve the URL of the created ingress using kubectl get ingress -n microcks. Before starting playing with Microcks, you'll have to connect to Keycloak component in order to configure an identity provider or define some users for the Microcks realm (see Keycloak documentation). Connection to Keycloak can be done using username and password stored into a microcks-keycloak-config secret created during setup.

Installing on OpenShift

The easiest way of installing Microcks for production use in most secured conditions is to do it on OpenShift. OpenShift in version 3.6 or greater is required. It is assumed that you have some kind of OpenShift cluster instance running and available. This instance can take several forms depending on your environment and needs :

When running on OpenShift, take care that you did not have the anyuid capability enabled. This prevents Microcks from using OpenShift internal Identity Provider. anyuid addon is enabled by default on Red Hat CDK. You may want to turn it off by executing oc adm policy remove-scc-from-group anyuid system:authenticated as this is a bad practice.
Then you have to ensure that Microcks templates for OpenShift are added and available into your Cluster. Templates come in 2 flavors: ephemeral or persistent. In persistent mode, template will claim a persistent volume during instanciation, such a volume should be available to your team / project on OpenShift cluster. Add the templates, by using these commands :
oc create -f https://raw.githubusercontent.com/microcks/microcks/master/install/openshift/openshift-ephemeral-full-template.yml -n openshift
oc create -f https://raw.githubusercontent.com/microcks/microcks/master/install/openshift/openshift-persistent-full-template.yml -n openshift

Once this is done can now create a new project and instanciate the template of your choice ; either using the OpenShift web console or the command line. You will need to fill up some parameters during creation such as:
  • the hostname for routes serving Microcks and embedded Keycloak (typically component_name-project-app_domain),
  • the URL for joining OpenShift Master,
  • a name for an OAuth Client that will be created apart the app creation.
Typically, you'll got this kind of commands for a local Minishift instance:

oc new-project microcks --display-name="Microcks"
oc new-app --template=microcks-persistent --param=APP_ROUTE_HOSTNAME=microcks-microcks.192.168.99.100.nip.io --param=KEYCLOAK_ROUTE_HOSTNAME=keycloak-microcks.192.168.99.100.nip.io --param=OPENSHIFT_MASTER=https://192.168.99.100:8443 --param=OPENSHIFT_OAUTH_CLIENT_NAME=microcks-client

After some minutes and components have been deployed, you should end up with a Spring-boot Pod, a MongoDB Pod, a Postman-runtime Pod, a Keycloak Pod and a PostgreSQL Pod like in the screenshot below.

Now you can retrieve the URL of the created route using oc get routes command and navigate to this URL to get started with Microcks. Depending on your environment, URL should be something like http://microcks-microcks.192.168.99.100.nip.io. By default, Microcks integrates with OpenShift identity provider through the use of Keycloak but you may configure some other providers later.

Installing using Docker Compose

You'll find instructions on how to use Docker Compose for installation here.

Building from binary/sources

To Do ...

Using Microcks

Now you are ready to use Microcks for deploying your own services and API mocks! Before that let's have the look at the application home screen and introduce the main concepts. Using the application URL after installation, we should land on this page with 2 main entry points : Services and Jobs.

As you may have guessed, Services is about browsing your [micro]-services and API repository, discovering and accessing documentation, mocks and tests. Jobs is another concept dedicated on how to fill this repository: it allows to periodically scan your Git or Subversion repository for checking new definition files that will be parsed and integrated as part of your [micro]-services and API repository. Indeed Jobs help discover new or modified Services. Before creating your own service definition files, let load some samples into Microcks for a test ride.

Loading samples

We provide different samples that illustrate different ways of creating service definitions. The 2 firsts are definition files realized using SoapUI and demonstrating SOAP and REST services. The third one is a definition file built using Postman and demonstrating the famous Petstore API. Using the Jobs entry point from home screen or top navigation bar, use the Job management page to add 3 new jobs. For each, you will be asked a name and a repository URL. Use the informations below:

  • Hello SOAP Service : https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloService-soapui-project.xml
  • Hello REST API : https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloAPI-soapui-project.xml
  • Petstore API : https://raw.githubusercontent.com/microcks/microcks/master/samples/PetstoreAPI-collection.json
Now that you have created your Jobs, you have to Activate them (this make them eligible to a periodically check) and to Start them (this make a forced refresh right now). After some moments and a page refresh, you should see the status of Jobs changed like in screenshot below:

Viewing services

Once sample jobs have been loaded, new Services has been discovered and added to your repository. You can now visit the Services entry point from top navigation bar or home screen. You should see 3 new services with basic informations on version and operations/resources handled by this services.

Viewing details

Now choosing the Petstore API microservice, you'll be able to access details, documentation and request/response samples for each operation/resource in the screen below. One important information here is the Mocks URL field: this is the endpoint where Microcks automatically deploy a mock for this operation. The table just below show request/response couples and a detailed URL with the HTTP verb showing how to invoke this mock.

Using this URL, you can call the exposed mock for Petstore API using the following curl command :

curl "http://microcks-microcks.192.168.99.100.nip.io/rest/Petstore%20API/1.0/pet/findByStatus?status=available&user_key=70f735676ec46351c6699c4bb767878a"

And you should receive the following response :

[{"id":190192062,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192063,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192285,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192654,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192671,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192727,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192736,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192768,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192878,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190192907,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":190193000,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"},{"id":-98125093,"category":{"id":-517488397,"name":"EJvNbK"},"name":"LuEfMZATrHz","photoUrls":["XCXOVVkaxa","gNwYqHEmC","nvCvphDeuqztysUBNed","W","vmrxRIViyXqumolLIeoB","JRqHVxk","tCUGbegVHoXajm","UiHppQn"],"tags":[{"id":727599428,"name":"RemggEDzxPljbrlktdWf"},{"id":1987753751,"name":"zWqdKAGHMmhPPlomljaNtuvm"},{"id":1251632392,"name":"BAgtgtKOxZGdsS"},{"id":-1813025208,"name":"OkKxtfAkCMEICbbQDVPi"},{"id":-730110346,"name":"WshDF"},{"id":2100951153,"name":"yxUFSknQEleIAQCoocl"},{"id":-2135188117,"name":"M"},{"id":1352243140,"name":"koKHsjysHXW"},{"id":1696778814,"name":"KaihiyarcZkIzkkquWPZ"},{"id":659492963,"name":"xqIzulcBPzWMyUpQwQK"},{"id":-2118372841,"name":"naYFGuHmqDqOpfHH"}],"status":"available"},{"id":8739826599258110549,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"}]%

Ta Dam !

What's next?

Now that you have basic information on how to setup and use Microcks, you can go further with :