Skip to content

README.tmpl.adoc

Latest commit

 

History

History
164 lines (112 loc) · 7.51 KB

README.tmpl.adoc

File metadata and controls

164 lines (112 loc) · 7.51 KB

ID4i CLI

ID4i provides globally unique IDs for single workpieces and a platform to manage, and exchange data bound to IDs in an inter-organizational manner. For details, please refer to http://id4i.de.

You can use the ID4i command line interface to …​

  • …​ perform manual tasks in ID4i

  • …​ include ID4i tasks in arbitrary shell scripts

  • …​ query ID4i manually or as part of existing workflows.

🔥
 ID4i CLI is currently a work in progress and should not be used in production; at least not without getting in touch first. More operations will be added in the future.

ID4i CLI is configurable using environment variables, a variety of configuration files and command line switches. See the Usage section or id4i help for details.

Since we do not have extensive experience in golang, we are thankful for contributions and/or bitching and nagging, especially in combination with pointers to more idiomatic alternative implementations.

Table of Contents

Usage

Prerequisites

For the CLI to be able to communicate with ID4i, you need an ID4i API key.

Complete the following steps to get from zero to your first successful ID4i CLI operation:

  1. If you have not already done, register a user on ID4i. Use Sandbox for care-free experimenting, and Production for production use.

  2. Create and activate an API key (the development manual has more info and screenshots)

    1. Navigate to API Keys → New API Key

    2. Note your API key secret and your API key ID

    3. Activate the API key

  3. Figure out your organization’s namespace (or even better, create a new one) on Organizations

  4. Configure the CLI to use your API key

    1. EITHER set ID4I_APIKEY, ID4I_SECRET, ID4I_BACKEND and ID4I_ORGANZATION environment variables

    2. OR use a configuration file in the current or your home directory named .id4i.properties (or .json or .yml) and set the properties apikey, secret, backend and organization there

    3. OR use command line flags for these parameters as described in Help

    4. OR any combination of the above. You get the point.

  5. Give your API key the corresponding permissions required to carry out the task you want. Go to the details page of your API key and set the permissions. You can learn about what happens in the background in the development manual.

You can either get a binary for your platform or run the ID4i CLI within Docker: docker run bluerainsoftware/id4i <args>. e.g. docker run bluerainsoftware/id4i help or docker run bluerainsoftware/id4i info -h.

For details on how to configure the image with your API key and other required properties, see https://hub.docker.com/r/bluerainsoftware/id4i-cli/

Help

(statically generated using update-readme.sh)

Development

If you need additional commands, feel free to jump in or let us know.

If you want to get involved, we classified some tasks as good first issues to get you started.

Prerequisites

  • Go 1.11.2

  • Go Dep, get it w/ go get -u -v github.com/golang/dep/cmd/dep

  • Docker, if you want to build the docker image. v18.06.1-ce and v17.03.0-ce are known to work

  • If you want to scaffold new commands, the cobra generator will help you: go get github.com/spf13/cobra/cobra

  • If you want to run the tests, you’ll need jq: https://stedolan.github.io/

Adding new commands

We use the awesome cobra [1] and viper [2] libraries.

To scaffold a new command, clone the repo and say cobra add <my command> -p rootCmd.

Open the generated command and implement your operation:

  • Define your parameters in init.

  • Validate your input, if required.

  • Use the operations exposed in ID4i (from rootCmd) to call the backend.

  • Use the OutputResult and DieOnError functions from rootCmd to report the result of your command.

  • Add your command to ./update-readme.sh so the README gets updated with the new command

You can find examples for each step in the existing commands.

If you want to debug the calls you are making, set the DEBUG environment variable to a non-empty value. This will cause the HTTP calls to be logged to the console.

ℹ️
 Please don’t forget to add tests for your new commands, see Test

Updating the API version

The API client is generated using go-swagger [3].

To update the client for the CLI, run ./generate-api-client.sh -c -d from the project root. Note that -d installs go-swagger locally and -c pulls the current API specification from ID4i production [4]

Run the tests and make required corrections in the existing commands if applicable. The ID4i change logs [5] are probably helpful.

Build

  • git clone git@github.com:BlueRainSoftware/id4i-cli.git $GOPATH/src/github.com/BlueRainSoftware/id4i-cli

  • cd $GOPATH/src/github.com/BlueRainSoftware/id4i-cli

  • dep ensure -v

  • go build -o id4i main.go

  • Update the README with the current help contents: ./update-readme.sh

Docker

To build the docker image, run docker build . -t id4i:<my tag>.

The README shown on DockerHub is the README.md file in this repository.

CI

CI Builds live on CircleCI, defined in .circleci/config.yml. Note that currently, the build artifacts (binary and docker image) are not stored anywhere, so you probably need to build it yourself. This will change, promise.

The docker image is built/pushed using the automatic builds on docker hub. The master branch is tagged latest, the develop branch develop. Tags starting with v are used as releases using the tag as version for the image.

Run

After building, you can run the binary w/ ./id4i.

Test

Integration tests live in test/tests. The preflight.sh script creates a user, saves the required information for id4i configuration to a temporary file and creates an id4i configuration file. It can also be used to download the testing framework (bats [6]) and to build the binary.

$ ./run-tests.sh -h
Run ID4i CLI tests
Usage: run-tests.sh [-h] [-v] [-i] [-p] [-c] [-b] [-t]
  -h	help - Show this help message.
  -v	version - Show version information.
  -i	install - Install Prerequisites
  -p	preflight - Run preflight script (provision ID4i test user)
  -c	cleanup - Clean up test results after successful tests
  -b	build - Build ID4i binary before testing (requires Go)
  -t	tap-format - Use TAP format test output (for CI reports)
ℹ️
 The tests always run against id4i-develop as of now.
1. https://github.com/spf13/cobra
2. https://github.com/spf13/viper
3. https://github.com/go-swagger/go-swagger, https://goswagger.io/
4. https://backend.id4i.de/docs/swagger.json; use the corresponding URL for other environments, e.g. https://sandbox.id4i.de/docs/swagger.json
5. https://github.com/BlueRainSoftware/support/tree/master/changelog
6. https://github.com/sstephenson/bats