Repository navigation
docs: add the Krini user guide - #137
Merged
Merged
Conversation
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>
Contributor
Reviewer's GuideDocumentationAdd the researcher-facing Krini guide, covering login, service selection, task and workflow use, current limitations, troubleshooting, and help.
Link the Krini guide from the researcher index and MkDocs navigation.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Documentation build overview
|
uniqueg
marked this pull request as ready for review
November 13, 2026 07:18
Contributor
Linked issuesChecked at commit 40cdfb1 #109 docs: write the Krini user guide · 2 of 4 met · 1 to check by hand
|
Contributor
There was a problem hiding this comment.
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
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
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
marked this pull request as ready for review
November 13, 2026 08:23
This was referenced Nov 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 ofresearchers/index.md.The page covers what the issue asks for, based on Krini's code, not on assumptions:
tes/tes-gateway,wes/wes-gateway), WES health checks, supported workflow types, service info.@elixir-cloud/tes1.0.1,@elixir-cloud/wes2.0.0-alpha.49).Krini has no user docs of its own (README and
docs/deployment.mdare 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 onstaging(merged 2026-11-11, krini#61). The page describesstagingat 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:outputinstead ofoutputs).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
stagingsource and thecloud-componentssources.python scripts/check_names.py: passedmkdocs build --strict: built without warningspytest: 25 passed, coverage 100%read -rsand 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.check_names.pypassed,mkdocs build --strictwithout warnings.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