Logging Library
[platform-oam.git] / docs / elkclient-api-developer-guide.rst
1 .. ===============LICENSE_START=======================================================
2 .. Acumos CC-BY-4.0
3 .. ===================================================================================
4 .. Copyright (C) 2019 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
5 .. ===================================================================================
6 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
7 .. under the Creative Commons Attribution 4.0 International License (the "License");
8 .. you may not use this file except in compliance with the License.
9 .. You may obtain a copy of the License at
10 ..
11 .. http://creativecommons.org/licenses/by/4.0
12 ..
13 .. This file is distributed on an "AS IS" BASIS,
14 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
17 .. ===============LICENSE_END=========================================================
18
19 ==============================================
20 Developer Guide for the Elastic Client Service 
21 ==============================================
22
23 This microservice provides Backup & Restore services to ELK components in the
24 Acumos machine-learning platform. It is built using the Spring-Boot platform.
25 This document primarily offers guidance for server developers.
26
27 Supported Methods and Objects
28 -----------------------------
29
30 The microservice endpoints and objects are documented using Swagger. A running
31 server documents itself at a URL like the following, but consult the server's
32 configuration for the exact port number (e.g., "9006") and context root
33 (e.g., "elkclient") to use::
34
35     http://localhost:9006/elkclient/swagger-ui.html
36
37 Building and Packaging
38 ----------------------
39
40 As of this writing the build (continuous integration) process is fully automated
41 in the Linux Foundation system using Gerrit and Jenkins. This section describes
42 how to perform local builds for development and testing.
43
44 Prerequisites
45 ~~~~~~~~~~~~~
46
47 The build machine needs the following:
48
49 1. Java version 1.8
50 2. Maven version 3
51 3. Connectivity to Maven Central to download required jars
52
53 Use maven to build and package the service into a single "fat" jar using this
54 command::
55
56     mvn clean install
57
58 Development and Local Testing
59 -----------------------------
60
61 This section provides information for running the server in a
62 production/development environment, assuming that the application is packaged
63 into a docker container for deployment.
64
65 Prerequisites
66 ~~~~~~~~~~~~~
67
68     1. Java version 1.8 in the runtime environment; i.e., installed in the
69        docker container
70     2. The username/password combination to access the database
71     3. The Nexus username/password combination to access.
72
73 Configuring the system
74 ~~~~~~~~~~~~~~~~~~~~~~
75
76 At runtime in production deployments, in addition to using a configuration file,
77 environment-specific configuration properties should be supplied using a block of
78 JSON in an environment variable called SPRING\_APPLICATION\_JSON. This can easily
79 be done using the deployment templates. The default SV Scanning templates
80 for use with docker-compose.
81
82 .. code:: bash
83
84    # Get the platform-oam repository 
85    $ git clone https://gerrit.acumos.org/r/platform-oam
86    # Select the Boreas branch
87    cd platform-oam
88    git checkout boreas
89    # See what environment configuration options are supported
90    cat platform-oam/acumos-elk-env.sh
91    # See the docker-compose deployment template with references to options
92    cat platform-oam/docker-compose.yml
93         
94 Launch Instructions
95 ~~~~~~~~~~~~~~~~~~~
96
97 To run the elkclient service in a local docker environment:
98
99 1. Build an image locally or use an image in the Acumos Nexus repositories.
100
101 2. Update environment variables as referenced by the template, either
102    directly or in acumos-elk-env.sh:
103
104    * ACUMOS_ELK_HOST: hostname Acumos elasticsearch.
105    * ELK_CLIENT_CRONSCHEDULE_CREATESNAPSHOT_TIME: Elk client schedule cron job for snapshot creation
106    
107 2. Use the docker-compose process that applies to your environment, e.g.
108
109    * for a standalone docker container::
110
111     docker-compose up -d elk-client
112