Skip to content

Commit

Permalink
Merge pull request #165 from ChannelFinder/mvn-wrapper
Browse files Browse the repository at this point in the history 
add a maven wrapper
  • Loading branch information
@shroffk
shroffk authored Nov 22, 2024
2 parents 1e3c29f + 194fcb7 commit 8232cd4
Show file tree
Hide file tree
Showing 4 changed files with 548 additions and 130 deletions.
19 changes: 19 additions & 0 deletions .mvn/wrapper/maven-wrapper.properties
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
wrapperVersion=3.3.2
distributionType=only-script
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
251 changes: 121 additions & 130 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,155 +1,138 @@
### Channel Finder
# Channel Finder

#### A simple directory service
ChannelFinder is a directory server, implemented as a REST style web service.
Its intended use is for control systems, namely the EPICS Control system.

ChannelFinder is a directory server, implemented as a REST style web service.
Its intended use is within control systems, namely the EPICS Control system, for which it has been written.
- [Documentation](https://channelfinder.readthedocs.io/en/latest/)
- [Releases](https://github.com/ChannelFinder/ChannelFinderService/releases)
- [Docker Containers](https://github.com/ChannelFinder/ChannelFinderService/pkgs/container/channelfinderservice)

* Motivation and Objectives
## Description

High level applications tend to prefer an hierarchical view of the control system name space. They group channel names by location or physical function. The name space of the EPICS Channel Access protocol, on the other hand, is flat. A good and thoroughly enforced naming convention may solve the problem of creating unique predictable names. It does not free every application from being configured explicitly, so that it knows all channel names it might be interested in beforehand.
* **Motivation and Objectives**

ChannelFinder tries to overcome this limitation by implementing a generic directory service, which applications can query for a list of channels that match certain conditions, such as physical functionality or location. It also provides mechanisms to create channel name aliases, allowing for different perspectives of the same set of channel names.
High level applications tend to prefer a hierarchical view of the control system name space. They group channel names
by location or physical function. The name space of the EPICS Channel Access protocol, on the other hand, is flat. A
good and thoroughly enforced naming convention may solve the problem of creating unique predictable names. It does not
free every application from being configured explicitly, so that it knows all channel names it might be interested in
beforehand.

* Directory Data Structure
ChannelFinder tries to overcome this limitation by implementing a generic directory service, which applications can
query for a list of channels that match certain conditions, such as physical functionality or location. It also
provides mechanisms to create channel name aliases, allowing for different perspectives of the same set of channel
names.

Each directory entry consists of a channel `<name>`, an arbitrary set of `<properties>` (name-value pairs), and an arbitrary set of `<tags>` (names).
* **Directory Data Structure**

* Basic Operation
Each directory entry consists of a channel `<name>`, an arbitrary set of `<properties>` (name-value pairs), and an
arbitrary set of `<tags>` (names).

An application sends an HTTP query to the service, specifying an expression that references tags, properties and their values, or channel names. The service returns a list of matching channels with their properties and tags, as JSON documents.
* **Basic Operation**

An application sends an HTTP query to the service, specifying an expression that references tags, properties and their
values, or channel names. The service returns a list of matching channels with their properties and tags, as JSON
documents.

#### API reference guide
## Installation

https://channelfinder.readthedocs.io/en/latest/
ChannelFinder is a Java EE5 REST-style web service. The directory data is held in a ElasticSearch index.

#### Installation
### Docker Compose

ChannelFinder is a Java EE5 REST-style web service. The directory data is held in a ElasticSearch index.
For using docker containers there is a barebones [docker compose file](./docker-compose.yml).

Collected installation recipes and notes may be found on [wiki pages](https://github.com/ChannelFinder/ChannelFinder-SpringBoot/wiki).
### Manual Installation

* Prerequisites

* JDK 17
* Elastic version 8.2.x
* <For authN/authZ using LDAP:> LDAP server, e.g. OpenLDAP

* setup elastic search
**Install**
Download and install elasticsearch (verision 8.2.0) from [elastic.com](https://www.elastic.co/downloads/past-releases/elasticsearch-8-2-0)
following the instructions for your platform.\
<Alternatively:> Install the elastic server from your distribution using a package manager.

* Build
```
# Debian 10
sudo apt-get install openjdk-17-jdk maven git curl wget
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.2.0-amd64.deb
sudo dpkg -i elasticsearch-8.2.0-amd64.deb
sudo systemctl start elasticsearch
#### Checkout and build ChannelFinder service source
git clone https://github.com/ChannelFinder/ChannelFinderService.git
cd ChannelFinderService
mvn clean install
* JDK 17
* Elastic version 8.11.x
* **For authN/authZ using LDAP:** LDAP server, e.g. OpenLDAP

```
#### Setup Elasticsearch

#### Start the service
Options:

* Using spring boot via Maven
- Download and install elasticsearch (version 8.11.0)
from [elastic.com](https://www.elastic.co) following the instructions for
your platform.
- Install the elastic server from your distribution using a package manager.
- Run Elasticsearch in a [docker container](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html)

```
mvn spring-boot:run
```
#### Running

* or using the jar
```bash
sudo apt-get install openjdk-17-jre git curl wget
sudo systemctl start elasticsearch # Or other command to run elastic search

```
java -jar target/ChannelFinder-4.7.0.jar
# Replace verison with the release you want
wget https://github.com/ChannelFinder/ChannelFinderService/releases/download/ChannelFinder-{version}/ChannelFinder-{version}.jar
java -jar target/ChannelFinder-*.jar
```

Other installation recipes can be found
on [the wiki pages](https://github.com/ChannelFinder/ChannelFinder-SpringBoot/wiki).

### Configuration

By default, the channelfinder service will start on port 8080 with the default settings. To start with a
different `application.properties` file:

```bash
java -Dspring.config.location=file:./application.properties -jar ChannelFinder-*.jar
```

The above command will start the channelfinder service on port 8080 with the default settings,
which use embedded ldap server with users and roles defined in the [`cf.ldif`](src/main/resources/cf.ldif) file.
The default authentication includes an embedded ldap server with users and roles defined in
the [`cf.ldif`](src/main/resources/cf.ldif) file.
Note that `cf.ldif` contains **default credentials** and should only be used during testing and evaluation.

#### Verification
### Verification

To check that the server is running correctly.
To check that the server is running correctly, visit [the default homepage](http://localhost:8080/). For more
information on the api see the [swagger docs endpoint](http://localhost:8080/swagger-ui/index.html).

```
$ curl --fail-with-body http://localhost:8080/ChannelFinder
{
"name" : "ChannelFinder Service",
"version" : "4.7.0",
"elastic" : {
"status" : "Connected",
"clusterName" : "elasticsearch",
"clusterUuid" : "sA2L_cpoRD-H46c_Mya3mA",
"version" : "8.2.0"
}
}
# Verify by creating a simple Channel using the demo auth
$ curl --location -u admin:adminPass --request PUT 'http://localhost:7070/ChannelFinder/resources/channels/test_channel' \
--header 'Content-Type: application/json' \
--data '{
"name": "test_channel",
"owner": "admin"
}'
$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/channels
...
$ curl --basic -u admin:adminPass --fail-with-body -H 'Content-Type: application/json' \
-X PUT -d '{"name":"foo", "owner":"admin"}' \
http://localhost:8080/ChannelFinder/resources/tags/foo
$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/tags
...
$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/tags
[{"name":"foo","owner":"admin","channels":[]}]
$ curl --basic -u admin:1234 --fail-with-body -X DELETE \
http://localhost:8080/ChannelFinder/resources/tags/foo
```
## Development

#### Start up options
It's strongly encouraged to use a modern IDE such as [Intelij](https://www.jetbrains.com/idea/)
and [Eclipse](https://eclipseide.org/).

You can start the channelfinder service with your own applications.properties file as follows:
* Prerequisites

```
mvn spring-boot:run -Dspring.config.location=file:./application.properties
```
or
```
java -Dspring.config.location=file:./application.properties -jar ChannelFinder-4.7.0.jar
```
* JDK 17
* Maven (via package manager or via the wrapper `./mvnw`) (version specified
in [the wrapper properties](./.mvn/wrapper/maven-wrapper.properties))

You can also start up channelfinder with demo data using the command line argument `demo-data` followed by an integer number `n`. For example, `--demo-data=n`. With this argument, `n*1500` channels will be created to simulate some of the most common types of devices found in accelerators like magnets, power supplies, etc...
For the following commands `mvn` can be interchangeably used instead via `./mvnw`

To build:

```bash
mvn clean install
```
java -jar target/ChannelFinder-4.7.*.jar --demo-data=1
java -jar target/ChannelFinder-4.7.*.jar --cleanup=1
```


To test:

```bash
mvn test
```
mvn spring-boot:run -Dspring-boot.run.arguments="--demo-data=1"
mvn spring-boot:run -Dspring-boot.run.arguments="--cleanup=1"

To run the server in development (you need a running version of Elasticsearch)

```bash
mvn spring-boot:run
```

#### Integration tests with Docker containers
### Integration tests with Docker containers

Purpose is to have integration tests for ChannelFinder API with Docker.

See `src/test/java` and package

* `org.phoebus.channelfinder.docker`

Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET) and curl commands (POST, PUT, DELETE) towards the application to test behavior (read, list, query, create, update, remove) and replies are received and checked if content is as expected.
Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET, POST, PUT,
DELETE) towards the application to test behavior (read, list, query, create, update, remove) and
replies are received and checked if content is as expected.

There are tests for properties, tags and channels separately and in combination.

Expand All @@ -159,42 +142,50 @@ Integration tests can be run in IDE and via Maven.
mvn failsafe:integration-test -DskipITs=false
```

See
See also

* [How to run Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_RUN.md)
* [Tutorial for Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_TUTORIAL.md)

#### ChannelFinder data managment

The [cf-manager](https://github.com/ChannelFinder/cf-manager) project provides tools to perform operations on large queries ( potentially the entire directory ).
Some examples of these operations include running checks to validate the pv names or producing reports about the number of active PVs, a list of IOC names, etc..

### Release ChannelFinder Server binaries to maven central

The Phoebus ChannelFinder service uses the maven release plugin to prepare the publish the ChannelFinder server binaries to maven central
The Phoebus ChannelFinder service uses the maven release plugin to prepare the publish the ChannelFinder server binaries
to maven central
using the sonatype repositories.

**Setup**
#### Setup

Create a sonatype account and update the maven settings.xml file with your sonatype credentials

```xml
<servers>
<server>
<id>phoebus-releases</id>
<username>username</username>
<password>*******</password>
</server>
</servers>
```
<servers>
<server>
<id>phoebus-releases</id>
<username>shroffk</username>
<password>*******</password>
</server>
</servers>
```

**Prepare the release**
`mvn release:prepare`
#### Prepare the release

```bash
mvn release:prepare
```

In this step will ensure there are no uncommitted changes, ensure the versions number are correct, tag the scm, etc..
A full list of checks is documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html):
A full list of checks is
documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html):

#### Perform the release

```bash
mvn release:perform
```

**Perform the release**
`mvn release:perform`
Checkout the release tag, build, sign and push the build binaries to sonatype.

**Publish**
Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish* button
#### Publish

Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish*
button
Loading

0 comments on commit 8232cd4

Please sign in to comment.