Boss Setup Tutorial

Setup for the Boss

Installation

intern is available on pypi and installable via pip:

pip install intern

Alternatively, you can install via git. Clone the repository from https://github.com/jhuapl-boss/intern and run

pip install -r requirements.txt

from the repository's location on your system.

Add <repository location> to your PYTHONPATH.

For example, on a *nix system, if intern was cloned to ~/intern:

export PYTHONPATH=$PYTHONPATH:~/intern

Account Setup

Create a Boss account by going to this address: https://api.bossdb.io/

You will be redirected to the Keycloak login page. Click on the Register link. After creating an account, you should be redirected to the token page. The token displayed in the text box will allow intern to perform operations using your user account. Place this token in the intern config file (described below).

Configuring intern

You must provide intern details on what server you which to connect to and your API key. There are several ways to do this, which are outlined below. The Remote class tries each of these methods in order and will use the first configuration found.

Configuration Dictionary

The first method allows you to directly set up the remote instance from code by passing in a dictionary. In this mode, all services supported by the Remote class will be configured the same.

config = {"protocol": "https",
          "host": "api.bossdb.io",
          "token": "mysecrettoken"}

rmt = BossRemote(config)

User Provided Configuration File

The path to a config file can be passed to the Remote class during construction. The format of the config file is INI style as provided by Python's configparser module.

from intern.remote.boss import BossRemote

# Create a remote configured with a custom config file.
rem2 = BossRemote('~/custom.cfg')

The config file has a separate section for each intern service to provide power users the ability to point at different servers if needed. Currently, those sections are:

• Project Service
• Metadata Service
• Volume Service

Each section has the following config parameters:

• protocol
• host
• token

protocol should be https unless you are communicating with an insecure server (this is highly unlikely for the Boss). host contains only the host name of the remote service. When intern sends requests, it will construct a URL using both protocol and host. token provides the identity information to the Boss so it knows which user is accessing the system.

Under normal circumstances, the values of the config parameters in each section will be identical. token is typically the only parameter that needs to be changed in the config file.

The example below is taken from https://github.com/jhuapl-boss/intern/blob/master/examples/example.cfg.

#
# Example config file for talking to the Boss API.
# Typically the settings for each service will be identical as shown here.
#
[Project Service]
protocol = https
host = api.bossdb.io
token = b1f674ec9cca51a8c21375da153d52322bfc6e3f

[Metadata Service]
protocol = https
host = api.bossdb.io
token = b1f674ec9cca51a8c21375da153d52322bfc6e3f

[Volume Service]
protocol = https
host = api.bossdb.io
token = b1f674ec9cca51a8c21375da153d52322bfc6e3f

Alternatively, you can simply specify a single section that will be used for all services

#
# Example config file for talking to the Boss API using a single section.
#
[Default]
protocol = https
host = api.bossdb.io
token = b1f674ec9cca51a8c21375da153d52322bfc6e3f

Default Configuration File

You can optionally place your configuration file at ~/.intern/intern.cfg and the Remote class will automatically load it. If you are on Windows, this path is C:\Users\[username]\.intern\intern.cfg.

from intern.remote.boss import BossRemote

# Assume a valid configuration file exists at ~/.intern/intern.cfg.
rmt = BossRemote()

Environment Variables

Lastly, you can configure intern using environment variables as shown below:

export INTERN_PROTOCOL=https
export INTERN_HOST=api.bossdb.io
export INTERN_TOKEN=b1f674ec9cca51a8c21375da153d52322bfc6e3f

from intern.remote.boss import BossRemote

# Assume a no configuration file exists at ~/.intern/intern.cfg.
rmt = BossRemote()