local.md

# Run 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](https://doc.arkindex.org/users/auth/#personal-token).

### 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

1. Open a web browser and browse to the Arkindex instance.

2. In the top-right user menu, click on **My repositories**.

3. Click on your worker, listed in the **Workers** column.

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

1. In the backend's Docker image, run:

   ```shell
   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:

```shell
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

1. In a shell, run:

   ```shell
   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

1. Activate the Python environment: run `workon X` where `X` is the name of your Python environment.
2. 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.