Skip to content

docs: add the Krini user guide - #137

Merged
uniqueg merged 3 commits into
mainfrom
docs/109-krini-user-guide
Nov 13, 2026
Merged

uniqueg merged 3 commits into
mainfrom
docs/109-krini-user-guide

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds the Krini user guide for researchers, docs/researchers/krini.md ("Use Krini"), with one nav entry under Researchers and one row in the table of researchers/index.md.

The page covers what the issue asks for, based on Krini's code, not on assumptions:

  • Log in with LS Login (sidebar menu or top bar), session renewal, logout (ends the Krini session only).
  • Request access: Krini has no access request yet (krini#43, krini#45), so the page points to an LS Login account and to cloud-service@elixir-europe.org.
  • Choose a service: TES and WES lists from the Cloud Registry (tes/tes-gateway, wes/wes-gateway), WES health checks, supported workflow types, service info.
  • Run a task / run a workflow: the fields of both forms, as the Cloud Components render them (@elixir-cloud/tes 1.0.1, @elixir-cloud/wes 2.0.0-alpha.49).
  • Find results: task details (logs, outputs) in the task list; for workflow runs, "View Details" doesn't open anything in Krini yet, so the page shows how to read a run's log and outputs from the WES API with the copied token.
  • Copying the access token, troubleshooting (Krini's own messages), what's coming (linked Krini issues), getting help.

Krini has no user docs of its own (README and docs/deployment.md are for developers and operators), so there was nothing generic to link instead; the page links those two for operators.

Which Krini the page describes

Production (https://krini.rahtiapp.fi/, deployed from master) still runs the old Vite app. The rewrite that D4.4 delivers (Next.js, Cloud Components, Cloud Registry) is on staging (merged 2026-11-11, krini#61). The page describes staging at commit c81a259 and says so in a short note at the top (maintainer's decision). Limits of that version are documented as limits, not hidden:

  • TES requests carry no token yet (krini#41, krini#44), so tasks only work on services that accept requests without one.
  • The TES form drops the Outputs (the component sends output instead of outputs).
  • WES "View Details" has no handler in Krini.

Verification

Light lane: the PR changes only docs and the nav (no code, CI, secrets or permissions), so the reviewer subagents were skipped; I reviewed the diff myself and checked every UI label, route and limit against the Krini staging source and the cloud-components sources.

  • python scripts/check_names.py: passed
  • mkdocs build --strict: built without warnings
  • pytest: 25 passed, coverage 100%
  • CI on this PR: all checks passed (PR title, Docs, Test, CI passed, CodeQL, Read the Docs preview build).
  • Sourcery review: 5 findings. Fixed 4 in 40cdfb1 (token read with read -rs and passed to curl on stdin; WES endpoint taken from Krini's service info instead of appending /ga4gh/wes/v1; warning that Krini sends the token to the chosen WES service; no CLI advice for services that need a token). The fifth ("describes staging, not production") was decided by the maintainer: document the rewrite (52085dd); answered and resolved.
  • After the fixes: check_names.py passed, mkdocs build --strict without warnings.
  • Rendered HTML checked: the tables nested in the numbered steps render as tables inside the list items.

The remaining gaps link their issues: krini#66 (run details), krini#67 (UI leftovers), cloud-components#574 (TES form drops outputs).

Declined review findings

None (light lane, no reviewer subagents).

Open questions

None. The maintainer decided to document the rewrite on staging (it replaces the current version soon); the warning at the top is now a short note.

Closes #109

🤖 Generated with Claude Code

Add a researcher page on Krini, the web portal: logging in with LS
Login, choosing TES and WES services from the Cloud Registry, running
and following tasks and workflows, reading run outputs through the API,
copying the access token, troubleshooting, and what is planned.

The page describes the rewritten Krini on the branch staging (commit
c81a259), which isn't deployed yet, and says so. Limits of that version
are documented as such: no token for TES services, task outputs not
passed on, no run details for workflows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Documentation

Add the researcher-facing Krini guide, covering login, service selection, task and workflow use, current limitations, troubleshooting, and help.

  • docs/researchers/krini.md L1-308

Link the Krini guide from the researcher index and MkDocs navigation.

  • docs/researchers/index.md L13
  • mkdocs.yml L117

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@read-the-docs-community

read-the-docs-community Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 elixir-on-cloud-docs | 🛠️ Build #35862130 | 📁 Comparing 52085dd against latest (8b38ab5)

  🔍 Preview build  

2 files changed
+ researchers/krini/index.html
± researchers/index.html

@uniqueg
uniqueg marked this pull request as ready for review November 13, 2026 07:18
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit 40cdfb1

#109 docs: write the Krini user guide · 2 of 4 met · 1 to check by hand

# Requirement Status Notes
1 Cover logging in, requesting access, running tasks and workflows, and finding results. ✅ Met The guide covers each of these topics.
2 Link Krini's generic docs instead of repeating them. ✅ Met The page links Krini's README and deployment guide.
3 Publish the guide in the Documentation Hub. 👀 Check by hand (external system) Check that the guide is published and accessible in the Documentation Hub.
4 Match the deployed Krini. ❌ Not addressed The guide explicitly describes the unreleased staging rewrite, while the deployed instance still runs the previous version.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 5 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/researchers/krini.md" line_range="220" />
<code_context>
+   chose in Krini and the run ID:
+
+    ```bash
+    export TOKEN='<the token that you copied>'
+    curl -H "Authorization: Bearer $TOKEN" \
+      "https://<WES service>/ga4gh/wes/v1/runs/<run ID>"
</code_context>
<issue_to_address>
**Bearer token is exposed locally**

When a reader runs the example with a real token in an interactive shell that records history or permits process inspection, `export TOKEN=...` records the token in shell history, and expanding `$TOKEN` puts it in `curl`'s process arguments. Anyone who can read those records or arguments can act as the user until the token expires.

Read the token without saving it in shell history, and pass it to `curl` through a mechanism that does not expose it in process arguments.

Also at `docs/researchers/krini.md:221-222`.
</issue_to_address>

### Comment 2
<location path="docs/researchers/krini.md" line_range="89-92" />
<code_context>
+
+- **TES:** services of the types `tes` and `tes-gateway`, e.g., TESK, Funnel
+  and the proTES gateway.
+- **WES:** services of the types `wes` and `wes-gateway` with an `https`
+  address. Krini checks each one: it shows its health and the number of
+  workflow types that it supports. You can't select a service that is
+  unreachable, and Krini leaves out services that answer with an error.
+  **Refresh**, at the top of the list, checks them again.
+
</code_context>
<issue_to_address>
**Untrusted services receive login tokens**

When a user selects an untrusted WES entry from the registry, krini sends the user's access token to the selected WES service, but the documented list criteria are service type, HTTPS and reachability—not whether the service is trusted. A malicious or compromised listed service can steal the bearer token and act as the user until it expires.

Warn users that selecting a WES service sends it their access token, and advise them to use only services they trust, with registry verification and sync status as a baseline.

Also at `docs/researchers/krini.md:177-178`.
</issue_to_address>

### Comment 3
<location path="docs/researchers/krini.md" line_range="118" />
<code_context>
+    work only on TES services that accept requests without a token. For the
+    others, use the API with your token (see [Using the
+    APIs](../partners-and-developers/apis.md)), or the [command
+    line](cli.md).
+
+1. Open **Tasks** and select **Create Task**.
</code_context>
<issue_to_address>
**Token-required TES tasks fail**

When a reader follows the command-line advice for a TES service that requires a token, `ga4gh-cli` does not send tokens, so the service returns `401 Unauthorized` and task creation fails.

Limit the CLI recommendation to TES services that accept requests without a token, or document a token-capable alternative.
</issue_to_address>

### Comment 4
<location path="docs/researchers/krini.md" line_range="222" />
<code_context>
+    ```bash
+    export TOKEN='<the token that you copied>'
+    curl -H "Authorization: Bearer $TOKEN" \
+      "https://<WES service>/ga4gh/wes/v1/runs/<run ID>"
+    ```
+
</code_context>
<issue_to_address>
**WES run lookup returns 404**

When the selected WES service's registered address already includes its API path, the example always appends `/ga4gh/wes/v1` to the service address; when that address is the registered API endpoint, the request duplicates the API path and the user cannot retrieve the run details or outputs.

Use the registered API endpoint as the base and append only `/runs/<run ID>`, or explain how to add the API path only when the address lacks it.
</issue_to_address>

### Comment 5
<location path="docs/researchers/krini.md" line_range="15-18" />
<code_context>
+are for developers and operators.
+
+!!! warning "Which Krini this page describes"
+    Krini is being rewritten. This page describes the new version, on the
+    branch `staging` of the [Krini repository][krini-repo] (commit
+    [`c81a259`](https://github.com/elixir-cloud-aai/krini/commit/c81a259)).
+    The instance at <https://krini.rahtiapp.fi/> still runs the previous
+    version, which looks different, until the new version is released
+    there. Parts of the new version are still in progress, so details can
</code_context>
<issue_to_address>
**Describes staging, not production**

The issue asks for a guide that matches deployed Krini. This page describes the `staging` rewrite and says the deployed instance still runs a different version.
</issue_to_address>

Sourcery assessment

Approval pending. 5 findings to address first.

Blocking findings: docs/researchers/krini.md:220, docs/researchers/krini.md:92, docs/researchers/krini.md:118, docs/researchers/krini.md:222, docs/researchers/krini.md:18


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/researchers/krini.md Resolved
Comment thread docs/researchers/krini.md Resolved
Comment thread docs/researchers/krini.md Resolved
Comment thread docs/researchers/krini.md Resolved
Comment thread docs/researchers/krini.md Resolved
Read the token without shell history and pass it to curl on stdin,
derive the WES endpoint from Krini's service info, warn that Krini
sends the token to the chosen WES service, and drop the CLI advice for
services that require a token (the CLI sends none).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg marked this pull request as draft November 13, 2026 07:45
Replace the warning about the staging version with a short note that
the guide describes the new Krini, as the maintainer decided, and link
the issues for the remaining gaps: krini#66 (run details), krini#67
(UI leftovers) and cloud-components#574 (task outputs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg marked this pull request as ready for review November 13, 2026 08:23
@uniqueg
uniqueg merged commit da6392c into main Nov 13, 2026
17 checks passed
@uniqueg
uniqueg deleted the docs/109-krini-user-guide branch November 13, 2026 08:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: write the Krini user guide

1 participant