README.md

   1 <!--
   2   ============LICENSE_START=======================================================
   3    Copyright (C) 2021 Bell Canada.
   4   ================================================================================
   5   Licensed under the Apache License, Version 2.0 (the "License");
   6   you may not use this file except in compliance with the License.
   7   You may obtain a copy of the License at
   8
   9        http://www.apache.org/licenses/LICENSE-2.0
  10
  11   Unless required by applicable law or agreed to in writing, software
  12   distributed under the License is distributed on an "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14   See the License for the specific language governing permissions and
  15   limitations under the License.
  16
  17   SPDX-License-Identifier: Apache-2.0
  18   ============LICENSE_END=========================================================
  19 -->
  20
  21 # Building and running CPS Temporal locally
  22
  23 ## Building Java Archive only
  24
  25 Following command builds Java executable jar to `target/cps-temporal-x.y.z-SNAPSHOT` JAR file
  26 without generating any docker images:
  27
  28 ```bash
  29 mvn clean install
  30 ```
  31
  32 ## Building Java Archive and local Docker image
  33
  34 Following command builds the JAR file and also generates the Docker image:
  35
  36 ```bash
  37 mvn clean install -Pdocker -Ddocker.repository.push=
  38 ```
  39
  40 ## Running via Docker Compose
  41
  42 `docker-compose.yml` file is provided to be run with `docker-compose` tool and local image previously built.
  43 It starts following services:
  44
  45 * CPS Temporal service (cps-temporal)
  46 * Postgres Timescale database (timescaledb)
  47 * Kafka broker (zookeeper and kafka)
  48
  49 Execute following command from project root folder to start all services:
  50
  51 ```bash
  52 docker-compose up
  53 ```
  54
  55 Then, use `kafkacat` tool to produce a data updated event into the Kafka topic:
  56
  57 ```bash
  58 docker run -i --rm --network=host edenhill/kafkacat:1.6.0 -b localhost:19092 -t cps.data-updated-events -D/ -P <<EOF
  59 {
  60     "schema": "urn:cps:org.onap.cps:data-updated-event-schema:v1",
  61     "id": "38aa6cc6-264d-4ede-b534-18f5c1f403ea",
  62     "source": "urn:cps:org.onap.cps",
  63     "type": "org.onap.cps.data-updated-event",
  64     "content": {
  65         "observedTimestamp": "2021-06-09T13:00:00.123-0400",
  66         "dataspaceName": "my-dataspace",
  67         "schemaSetName": "my-schema-set",
  68         "anchorName": "my-anchor",
  69         "data": {
  70             "interface": {
  71                 "name": "itf-1",
  72                 "status": "up"
  73             }
  74         }
  75     }
  76 }
  77 EOF
  78 ```
  79
  80 Finally, verify that CPS Temporal data is persisted as expected:
  81
  82 ```bash
  83 psql -h localhost -p 5433 -d cpstemporaldb -U cpstemporal -c \
  84   "select * from network_data order by created_timestamp desc limit 1"
  85 ```
  86
  87 ## Alternative local db setup
  88
  89 A Postgres instance with Timescale extension can be started by running the following command:
  90
  91 ```
  92 docker run --name postgres-cps-temporal -p 5433:5432 -d \
  93   -e POSTGRES_DB=cpstemporaldb \
  94   -e POSTGRES_USER=cpstemporal \
  95   -e POSTGRES_PASSWORD=cpstemporal \
  96   timescale/timescaledb:2.5.1-pg14
  97 ```
  98
  99 [Liquibase](https://www.liquibase.org/) is used to manage database schema changes and versions.
 100 Then, the database schema is updated when the application is started or by running the following command:
 101
 102 ```
 103 mvn org.liquibase:liquibase-maven-plugin:4.3.2:update \
 104   -Dliquibase.url=jdbc:postgresql://localhost:5433/cpstemporaldb \
 105   -Dliquibase.username=cpstemporal \
 106   -Dliquibase.password=cpstemporal \
 107   -Dliquibase.changeLogFile=db/changelog/changelog-master.xml
 108 ```
 109
 110 ## Accessing services
 111
 112 Swagger UI is available to discover service endpoints and send requests.
 113
 114 * `http://localhost:<port-number>/swagger-ui.html`
 115