[ https://issues.apache.org/jira/browse/METRON-503?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15874950#comment-15874950 ]
ASF GitHub Bot commented on METRON-503: --------------------------------------- Github user merrimanr commented on a diff in the pull request: https://github.com/apache/incubator-metron/pull/316#discussion_r102076209 --- Diff: metron-interface/metron-rest/src/test/resources/README.vm --- @@ -0,0 +1,142 @@ +#[[#]]# Metron REST + +This module provides a RESTful API for interacting with Metron. + +#[[##]]# Prerequisites + +* A running Metron cluster +* Java 8 installed +* Storm CLI and Metron topology scripts (start_parser_topology.sh, start_enrichment_topology.sh, start_elasticsearch_topology.sh) installed + +#[[##]]# Installation +1. Package the application with Maven: +``` +mvn clean package +``` + +1. Untar the archive in the target directory. The directory structure will look like: +``` +bin + start_metron_rest.sh +lib + metron-rest-$METRON_VERSION.jar +``` + +1. Create an `application.yml` file with the contents of [application-docker.yml](src/main/resources/application-docker.yml). Substitute the appropriate Metron service urls (Kafka, Zookeeper, Storm, etc) in properties containing `${docker.host.address}` and update the `spring.datasource.*` properties as needed (see the [Security](#security) section for more details). + +1. Start the application with this command: +``` +./bin/start_metron_rest.sh /path/to/application.yml +``` + +#[[##]]# Usage + +The exposed REST endpoints can be accessed with the Swagger UI at http://host:port/swagger-ui.html#/. The default port is 8080 but can be changed in application.yml by setting "server.port" to the desired port. + +#[[##]]# Security + +The metron-rest module uses [Spring Security](http://projects.spring.io/spring-security/) for authentication and stores user credentials in a relational database. The H2 database is configured by default and is intended only for development purposes. The "dev" profile can be used to automatically load test users: +``` +./bin/start_metron_rest.sh /path/to/application.yml --spring.profiles.active=dev +``` + +For [production use](http://docs.spring.io/spring-boot/docs/1.4.1.RELEASE/reference/htmlsingle/#boot-features-connect-to-production-database), a relational database should be configured. For example, configuring MySQL would be done as follows: + +1. Create a MySQL user for the Metron REST application (http://dev.mysql.com/doc/refman/5.7/en/adding-users.html). + +1. Connect to MySQL and create a Metron REST database: +``` +CREATE DATABASE IF NOT EXISTS metronrest +``` + +1. Add users: +``` +use metronrest; +insert into users (username, password, enabled) values ('your_username','your_password',1); +insert into authorities (username, authority) values ('your_username', 'ROLE_USER'); +``` + +1. Replace the H2 connection information in the application.yml file with MySQL connection information: +``` +spring: + datasource: + driverClassName: com.mysql.jdbc.Driver + url: jdbc:mysql://mysql_host:3306/metronrest + username: metron_rest_user + password: metron_rest_password + platform: mysql +``` + +1. Add a dependency for the MySQL JDBC connector in the metron-rest pom.xml: +``` +<dependency> + <groupId>mysql</groupId> + <artifactId>mysql-connector-java</artifactId> + <version>${mysql.client.version}</version> +</dependency> +``` + +1. Follow the steps in the [Installation](#installation) section + +#[[##]]# API + +Request and Response objects are JSON formatted. The JSON schemas are available in the Swagger UI. + +| | +| ---------- | +#foreach( $restControllerInfo in $endpoints ) +| [ `$restControllerInfo.getMethod().toString() $restControllerInfo.getPath()`](#$restControllerInfo.getMethod().toString().toLowerCase()-$restControllerInfo.getPath().toLowerCase().replaceAll("/", ""))| +#end + +#foreach( $restControllerInfo in $endpoints ) +#[[###]]# `$restControllerInfo.getMethod().toString() $restControllerInfo.getPath()` + * Description: $restControllerInfo.getDescription() +#if($restControllerInfo.getParameterDescriptions().size() > 0) + * Input: +#end +#foreach( $parameterDescription in $restControllerInfo.getParameterDescriptions().entrySet()) + * $parameterDescription.getKey() - $parameterDescription.getValue() +#end + * Returns: +#foreach( $response in $restControllerInfo.getResponses()) + * $response.getCode() - $response.getMessage() +#end + +#end + +#[[##]]# Testing + +Profiles are includes for both the metron-docker and Quick Dev environments. + +#[[###]]# metron-docker + +Start the [metron-docker](../../metron-docker) environment. Build the metron-rest module and start it with the Spring Boot Maven plugin: +``` +mvn clean package +mvn spring-boot:run -Drun.profiles=docker,dev +``` +The metron-rest application will be available at http://localhost:8080/swagger-ui.html#/. + +#[[###]]# Quick Dev + +Start the [Quick Dev](../../metron-deployment/vagrant/quick-dev-platform) environment. Build the metron-rest module and start it with the Spring Boot Maven plugin: +``` +mvn clean package +mvn spring-boot:run -Drun.profiles=vagrant,dev +``` +The metron-rest application will be available at http://localhost:8080/swagger-ui.html#/. + +To run the application locally on the Quick Dev host, package the application and scp the archive to node1: +``` +mvn clean package +scp ./target/metron-rest-$METRON_VERSION-archive.tar.gz root@node1:~/ +``` +Login to node1 and unarchive the metron-rest application. Start the application on a different port to avoid conflicting with Ambari: +``` +java -jar ./lib/metron-rest-0.3.0.jar --spring.profiles.active=vagrant,dev --server.port=8082 --- End diff -- Done > Metron REST API > --------------- > > Key: METRON-503 > URL: https://issues.apache.org/jira/browse/METRON-503 > Project: Metron > Issue Type: New Feature > Reporter: Ryan Merriman > Assignee: Ryan Merriman > Attachments: Metron REST API.docx > > > As discussed on the dev list ([DISCUSS] Metron REST API Requirements), this > Jira includes adding a REST API to Metron. -- This message was sent by Atlassian JIRA (v6.3.15#6346)