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.

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

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

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

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

= Testing = = Next steps =