Service-template-node/GettingStarted

This guide will walk you through the most basic steps needed to create a new service based on the service-template-node project. As an example we'll build a micro-service that does nothing more than convert an SVG stored in MediaWiki to PNG, and return it the user. We will call this new service svg2png.

= Creating the service = The service-template-node project is meant to act as a skeleton, providing new projects with all of the boiler plate needed to hit the ground running with a web service that conforms to best-practices. To create your new service, start by cloning.

$ git clone https://github.com/wikimedia/service-template-node.git svg2png

Project metadata
In the top-level of your new project is a file named  that contains important meta-data. After cloning the new repository, this meta-data naturally pertains to the service-template-node project, so open it with the editor of your choice, and customize it for our svg2png service. At a minimum, you should update the,  ,  ,  ,  , bug tracking URL , and.

Note: A complete description of  is beyond the scope of this document; You are encouraged to consult the documentation for.

Configuration
Our newly minted service reads its configuration at startup from a YAML configuration file. This file can be used to configure a number of the features inherited from service-runner, (logging, metrics, etc), but for the time-being, let's configure the service name, and a port number to listen on.

Open the included example  and configure a service   and  :

Dependencies
Finally, before we can begin implementing our service, we need to ensure that we have all required dependencies. service-template-node provided us with a list of sensible default dependencies in, but we must explicitly install them ourselves. Let's do that now:

$ npm install ...

This will download the NodeJS modules specified in, including any transitive dependencies, to a directory named   where they can be loaded by our service.

Specific to our service though, is the need to convert SVG graphic files to PNG format, and fortunately for us there exist NodeJS bindings for the excellent librsvg library. The only caveat here, is that in addition to downloading the Javascript source,  also needs to compile and link some architecture-specific code. This means that you must have librsvg installed on your host platform first.

On Debian-based systems, this is as easy as:

$ sudo apt-get install librsvg2-dev

With librsvg installed, we can now invoke  to complete the installation.

$ npm install --save librsvg

Note: the  argument above is a convenience that instructs   to append librsvg to the list of dependencies in  .

= Adding a route = The purpose of a route is to map a resource (URL) to the code responsible for processing its requests.

Let's think for a moment about our SVG-to-PNG conversion service, and what a route for conversions should look like.

By convention, we want each of our routes to be per-domain, so that services can operate against an arbitrary number of MediaWiki instances. And, we include a version so that we can make changes later without disrupting existing users. These conventions are so common that routes automatically loaded from the  subdirectory support templated URL parameters for the domain and version out-of-the-box.

http://host:port/{domain}/{version}/

For our service, we also need the name of the SVG file to convert.

http://host:port/{domain}/{version}/png/{file}

Note: We could just append our filename parameter, assume that conversions to PNG are implicit, but adding the  element above buys us a little flexibility should we decide to extend the service to other formats later.

For example:

http://localhost:8825/commons.wikimedia.org/v1/png/Square_funny

Creating the route module
Create your new route module by copying the example, to.

Next, edit, and change the exported function (at the bottom of the file), so that it looks something like:

= Testing = = Next steps =