Getting started

This text will offer you the basics to get started with mu.semte.ch.  The theory is explained in An Ecosystem of User-facing Microservices supported by Semantic Models, this guide is for the practically oriented.

Installation

All mu.semte.ch applications rely on Docker and Docker Compose.  Install those following the respective links.

Each microservice, and all related tooling, is offered in the form of Docker images.

When starting a new project, a good basis is https://github.com/mu-semtech/mu-project.  Clone this repository, or copy its contents, as it will be the basis for this tutorial.

git clone https://github.com/mu-semtech/mu-project.git

Using microservices

Suppose we want to reuse the madnificent/books-service.  This service, like all other publicly available services, should be hosted on Docker Hub.  The Docker image can be found at https://hub.docker.com/r/madnificent/books-service.  We’ll include this service, and proxy the relevant requests to our newly imported service.

Include books-service

We add the microservice in the docker-compose.yml file of our mu-project.  Just above the resource line, we can add the following:

=    volumes:
=      - ./data/db:/data
+    books:
+      image: madnificent/books-service:1.0.0
+      links:
+        - db:database
=  resource:
=    image: semtech/mu-cl-resources:1.10.1

We also ensure the dispatcher knows the books service, so we can use it to forward the request later.  This is done in the section on the dispatcher:

=    links:
=      - resource:resource
+      - books:books
=    volumes:

Dispatch books & authors requests

In the config/dispatcher/dispatcher.ex file, all proxy rules are defined.  They’re matched top to bottom of the file.  You can copy one of the examples to dispatch a new request.

The proxy service needs to know the books service.  See the previous section for the necessary link.

We add a route for “/books/” and for “/authors/” like so:

=  # match "/themes/*path" do
=  #   Proxy.forward conn, path, "http://resource/themes/"
=  # end
=
+  match "/books/*path" do
+    Proxy.forward conn, path, "http://books/books/"
+  end
+
+  match "/authors/*path" do
+    Proxy.forward conn, path, "http://books/authors/"
+  end
+
=  match _ do
=    send_resp( conn, 404, "Route not found.  See config/dispatcher.ex" )
=  end

Ember in the frontend

Our end-users access the services through EmberJS application.  This provides us with an integrated, styled and flexible view of the enabled microservices.  We’ll create a new ember application to allow end-users to list, create, and delete authors.  The advised way to build and develop EmberJS applications is using ember-cli.

You can install ember-cli from ember-cli.com, or you can use the ember-docker found at https://github.com/madnificent/docker-ember .  Our examples assume you’ll use ember-docker.

Build a new app

First we create the new application.  The command is short, but it may take a while to fetch all NPM dependencies.  Grab a coffee while the computer works for you.

edi ember new books

Live reloading changes

Let’s see if our new application runs.  Go into the books directory and run the ember serve command (available as eds).  Once the files have compiled, you can visit the site in your browser at localhost:4200.

cd books
eds --proxy http://host

The proxy connects to our localhost on port 80 (yes, it’s called host in the ember-docker, rather than localhost).  We’ll use this later to fetch content from the microservices.  Let’s alter the title of our application, the browser’s view will update automatically.  Open app/application.hbs and change the following:

-  <h2 id="title">Welcome to Ember</h2>
+  <h2 id="title">My books</h2>

Boom, automatic updates in the browser.

Connecting

EmberJS applications roughly follow the Web-MVC pattern.  The applications have a rigid folder-structure, most content being in the app folder.  Ember-cli uses generators to generate basic stubs of content.  We create the books model, route and controller using ember-cli.  Check the helpers for ember generate model, ember generate route and ember generate controller, or the following:

edi ember generate resource book title:string isbn:string
edi ember generate controller book

The terminal output shows the created and updated files.  (note: generating new files can make watched files fail in Docker, just kill and restart eds should that happen.)

We will fetch all books and render them in our template.  In routes/book.js

=  export default Ember.Route.extend({
+    model: function() {
+      this.store.findAll('books');
+    }
=  });

We’ll display the found records in our template so we’re able to see the created records later on.  Add the following to templates/route.hbs

+  <ul>
+  {{#each model as |book|}}
+    <li>{{book.title}} <small>{{book.isbn}}</small></li>
+  {{/each}}
+  </ul>

Creating new books

We’ll add a small input-form through which we can create new books at the bottom of our listing.  Two input fields and a create button will suffice for our example.

In the app/templates/book.hbs template, we’ll add our create fields and button:

+  <hr />
+  <dl>
+    <dt>Book title</dt>
+    <dd>{{input value=newBookTitle placeholder="Thinking Fast and Slow"}}</dd>
+    <dt>ISBN</dt>
+    <dd>{{input value=newIsbn placeholder="978-0374533557"}}</dd>
+  </dl>
+  <button {{action "createBook"}}>Create</button>

We’ll add this action in the controller and make it create the new book.  In app/controllers/book.hbs add the following:

=  export default Ember.Controller.extend({
+    actions: {
+      createBook: function() {
+        // create the new book
+        const book = this.store.createRecord('book', {
+          title: this.get('newTitle'),
+          isbn: this.get('newIsbn')
+        });
+        book.save()
+        // clear the input fields
+        this.set('newTitle', '');
+        this.set('newIsbn', '');
+      }
+    }
=  });

Removing books

Removing books follows a similar path to creating new books.  We add a delete button to the template, and a delete action to the controller.

In app/templates/book.hbs we alter:

=    <dt>ISBN</dt>
=    <dd>{{input value=newIsbn placeholder="978-0374533557"}}</dd>
+    <dt>Actions</dt>
+    <dd><button {{action "removeBook" book}}>Remove</button>
=  </dl>

In app/controllers/book.hbs we alter:

=        this.set('newTitle', '');
=        this.set('newIsbn', '');
+      },
+      removeBook: function(book) {
+        book.destroyRecord();
=      }
=    }