A Cyclades Service Engine Nyxlet/service for logging data from incoming requests

Basic Features

• Very basic request to log file functionality

Overview

• This product is provided under the terms of the BSD license, please see "LICENSE" for more information

• Although this product is used in production enviroments, it is currently being transitioned to an Open Source Software project. That being said, there will be aspects of this project that will need refinement as its maturing process as an Open Source Software project progresses (documentation, APIs, bugs etc…​). We are looking forward to the feedback and contributions that will improve this product for the OSS community.

• More documentation will be viewable online shortly. In the meantime, you will need to generate the current documentation from this source distribution. Instructions on how to do this will be included below as part of the Build And Deployment Instructions (*nix and Mac OS X platforms) section

• The terms "Service" and "Nyxlet" are synonymous with respect to Cyclades SOA. A Nyxlet is simply a service module that is pluggable into the Cyclades Service Engine. We will offer a set of utility Nyxlets to build and/or deploy shortly (like this one). Each will exist as an independent repository. Developers will also be encouraged to offer their Nyxlets to the community.

• This product has not been tested on, though should also work for Windows installations. The provided supplemental shell scripts are an exception and will not run on a typical Windows installation (the shell scripts to generate Nyxlet templates, generate documentation etc…​). Windows support for these items is on the to do list.

Build And Deployment Instructions (*nix and Mac OS X platforms)

Overview

This document describes the steps involved for Service (Nyxlet) developers and end users to build and deploy this Nyxlet. You must have Gradle installed to build. You must additionally have a running Cyclades Engine instance if a deployment is to be done. After we are done, you will have built and deployed this Nyxlet. Please follow the instructions below.

Build The Nyxlet

1. Install Gradle (if you do not already have it): http://www.gradle.org

2. Install Tomcat (if you do not already have it): http://tomcat.apache.org (We’re running on Tomcat 7) This could be a standard installation on any host, local or remote

3. Download and install (extract) a stable version of this repository (the Nyxlet Source Distribution) within a directory of choice (example: "/cycladessoa/nyxlets")

   1. https://github.com/cycladessoa/nyxlet-log/archive/v1.0.0.31.zip (We’ll assume the extracted directory is "/cycladessoa/nyxlets/log" for our purposes)

4. From within the directory "/cycladessoa/nyxlets/log" run the command gradle clean build

5. The Cyclades Service Engine binary distribution exists within a Nyxlet’s workspace build/libs directory after a successful build. This will be in the form of a "cyclades*.war" file. Simply copy this file to your Tomcat installation’s "webapps" directory and be sure to name it "cyclades.war".

6. Restart Tomcat and verify the installation

   1. http://localhost:8080/cyclades (Core Cyclades Service Engine status page should be displayed without error)

   2. http://localhost:8080/cyclades?action=help (Help page displays without error)

7. Deploy the Nyxlet to a running Cyclades Engine Instance

   1. If running on localhost, simply run the command gradle deploy from within the "/cycladessoa/nyxlets/log" directory, by default localhost will be the deployment target

   2. If running on another machine, or set of machines, modify your gradle.properties file prior to running the command gradle deploy

      1. Modify the "base_engine_url_list" property in "/cycladessoa/nyxlets/log/gradle.properties". This can be a comma separated list if deploying to multiple nodes

Example non-localhost configuration for two machines

base_engine_url_list={"url":"http://server1.mycompany.org:8080/cyclades","password":""},{"url":"http://server2.mycompany.org:8080/cyclades","password":""}

• You should be able to verify your Nyxlet is loaded by going to the following URL in your browser: http://localhost:8080/cyclades?action=loaded

• You should be able to view all available actions on your Nyxlet by going to the following URL in your browser: http://localhost:8080/cyclades/log?data-type=xml&action=listactions

Generate Current Documentation

1. Install Gradle (if you do not already have it): http://www.gradle.org

2. Download and install "AsciiDoc" (if you do not already have it): http://www.methods.co.nz/asciidoc

3. From within the base directory of your Nyxlet Source Distribution, run the command ./doc_gen.sh . generated_docs If you have not previously downloaded and installed the Nyxlet Source Distribution, please do the following before generating the documentation:

   1. Download and install (extract) a stable version of this repository (the Nyxlet Source Distribution) within a directory of choice (example: "/cycladessoa/nyxlets")

      1. https://github.com/cycladessoa/nyxlet-log/archive/v1.0.0.31.zip (We’ll assume the extracted directory is "/cycladessoa/nyxlets/log" for our purposes)

4. Open the file "/cycladessoa/nyxlets/log/generated_docs/index.html" in a browser window

Note	Please keep in mind this is an initial version of the documentation and we will be working on improvements throughout this project.

Naming

Terms

• STROMA: (protocol) Service TRansaction Orchestration Messaging Architecture

• X-STROMA: (protocol) "Trans", or "across" STROMA

• Nyxlet: A service module that is pluggable into the Cyclades Service Engine

Etymons

• "Stroma": Wikipedia (animal tissue), the connective, functionally supportive framework of a biological cell, tissue, or organ

• "Nyx": Wikipedia (Νύξ, "night") – Nox in Latin translation – is the Greek goddess (or personification) of the night. A shadowy figure, Nyx stood at or near the beginning of creation, and was the mother of other personified gods such as Hypnos (Sleep) and Thánatos (Death)