Running your worker locally¶

Once you have implemented a worker, you can run it on some Arkindex elements on your own machine to test it.

Warning

This section has been deprecated as of the latest version of base-worker.

Retrieving credentials¶

For a worker to run properly, you will need two types of credentials:

An API token that gives the worker access to the API
A worker version ID that lets the worker send results to Arkindex and report that those come from this particular worker version

Retrieving a token¶

For the worker to run, you will need an Arkindex authentication token. You can use your own account’s token when testing on your own machine.

You can retrieve your personal API Token from your profile page.

Retrieving a worker version ID¶

A worker version ID will be required in order to publish results. If your worker does not create any Arkindex element, classification, transcription, etc., you may skip this step.

If this particular worker was already configured on this instance, you can use its existing worker version ID; otherwise, you will need to ask an Arkindex administrator to create a fake version ID.

To retrieve a worker version ID from an existing worker¶

Open a web browser and browse to the Arkindex instance.
In the top-right user menu, click on My repositories.
Click on your worker, listed in the Workers column.
Rewrite the URL in your browser’s address bar, to look like https://<arkindex_url>/api/v1/workers/<worker_id>/versions/
- Replace process by api/v1
- Add a slash character (/) at the end

In the JSON output from this API endpoint, the first value next to "id" is the worker version ID.

To create a fake worker as an administrator¶

This action can only be done as an Arkindex administrator with shell access.

In the backend’s Docker image, run:

arkindex fake_worker_version --name <NAME> --slug <SLUG> --url <URL>

Replace <NAME>, <SLUG> and <URL> with the name, slug and GitLab repository URL, respectively.

A Git repository is created with a fake OAuth access token. A fake Git revision is added to this repository, and a fake worker version from a fake worker is linked to this revision. You should get the following output:

Created a worker version: 392bd299-bc8f-4ec6-aa3c-e6503ecc7730

Warning

This feature should only be used when a normal worker cannot be created using the Git workflow.

Setting credentials¶

In a shell you need to set 3 environment variables to transmit your credentials and Arkindex instance information to the worker:

ARKINDEX_API_URL: URL that points to the root of the Arkindex instance you are using.
ARKINDEX_API_TOKEN: The API token you retrieved earlier, on your profile page.
WORKER_VERSION_ID: The worker version ID you retrieved earlier. Can be omitted if the worker does not create new data in Arkindex.

To set credentials for your worker¶

In a shell, run:

export ARKINDEX_API_URL="https://arkindex.teklia.com"
export ARKINDEX_API_TOKEN="YOUR_TOKEN_HERE"
export WORKER_VERSION_ID="xxxxx"

Warning

Do not add these instructions to a script such as .bashrc; this would mean storing credentials in plaintext and can lead to security breaches

Running your worker¶

With the credentials configured, you can now run your worker. You will need a list of element IDs to run your worker on, which can be found in the browser’s address bar when browsing an element on Arkindex.

To run your worker¶

Activate the Python environment: run workon X where X is the name of your Python environment.
Run worker-X, where X is the __package name of your worker, followed by --element=Y where Y is the ID of an element. You can repeat --element as many times as you need to process multiple elements.