Skip to content

About

A RESTful directory services for a list channels

Resources

Stars

11 stars

Watchers

4 watching

Forks

Repository files navigation

Channel Finder

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

Description

  • Motivation and Objectives

    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.

    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.

  • Directory Data Structure

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

  • 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.

Installation

ChannelFinder is a Spring Boot REST-style web service. The directory data is held in an Elasticsearch index.

Docker Compose

For using docker containers there is a barebones docker compose file.

Manual Installation

  • Prerequisites

    • JDK 25
    • Elastic version 8.18.x
    • For authN/authZ using LDAP: LDAP server, e.g. OpenLDAP

Setup Elasticsearch

Options:

  • Download and install elasticsearch (version 8.18.0) from elastic.com following the instructions for your platform.
  • Install the elastic server from your distribution using a package manager.
  • Run Elasticsearch in a docker container

Running

sudo apt-get install openjdk-25-jre git curl wget
sudo systemctl start elasticsearch # Or other command to run elastic search

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

Other installation recipes can be found on the wiki pages.

Configuration

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

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

The default authentication is demo_auth, with users, passwords and roles set by the demo_auth.* properties in application.properties. An embedded LDAP server with users and roles defined in the cf.ldif file can be enabled with embedded_ldap.enabled=true. Note that both contain default credentials and should only be used during testing and evaluation.

Verification

To check that the server is running correctly, visit the default homepage. For more information on the api see the swagger docs endpoint.

Development

It's strongly encouraged to use a modern IDE such as IntelliJ IDEA or Eclipse.

  • Prerequisites

The commands below use the Maven wrapper ./mvnw. An installed mvn works as well.

To build:

./mvnw clean install

To test:

./mvnw test

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

./mvnw spring-boot:run

Integration tests

Integration tests (*IT) are skipped by default. Those that need Elasticsearch start a single Elasticsearch container with Testcontainers on a random port, so only a running Docker engine is required. The same run includes the Docker integration tests, which build a ChannelFinder image from the jar in target/. The commands therefore start with package, which builds the jar and also runs the unit tests. The test-compile after package is also needed. Failsafe otherwise loads the classes from the repackaged Spring Boot jar, and the tests fail with NoClassDefFoundError.

./mvnw package test-compile failsafe:integration-test failsafe:verify -DskipITs=false

To run them against an Elasticsearch that is already running instead, pass its URL:

./mvnw package test-compile failsafe:integration-test failsafe:verify -DskipITs=false -Delasticsearch.host_urls=http://localhost:9200

The Elasticsearch version of the container is the elasticsearch.server.version property in pom.xml. It defaults to the version of the Elasticsearch client. To test against another version, override it:

./mvnw package test-compile failsafe:integration-test failsafe:verify -DskipITs=false -Delasticsearch.server.version=8.19.0

compose.yml and src/test/resources/compose.yml set their own Elasticsearch image and do not follow this property.

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, 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.

Integration tests can be run in IDE and via Maven. This command runs only these tests:

./mvnw package test-compile failsafe:integration-test failsafe:verify -DskipITs=false -Pintegrationtest-docker

See also

Release ChannelFinder Server binaries to maven central

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

Setup

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

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

Prepare the release

./mvnw release:prepare

This step will ensure there are no uncommitted changes, ensure the version numbers are correct, tag the scm, etc.. A full list of checks is documented here:

Perform the release

./mvnw release:perform

Checkout the release tag, build, sign and push the build binaries to sonatype.

Publish

Open the staging repository in sonatype and hit the publish button

About

A RESTful directory services for a list channels

Resources

Stars

11 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages