Deployment¶
How to run the container image of Krini, pass it its settings, and prepare the login provider and the TES and WES services for it. On Kubernetes or OpenShift, install Krini with the Helm chart.
Container image¶
Branches and tags¶
dev is the default branch: all pull requests go into it, and CI runs on
pull requests into it and on pushes to it. main only moves forward to
released commits, and releases are made from v* tags (see
Releasing). dev was formerly called staging (the
branch dev-legacy holds the older code, and main was called
master).
The Docker image of the Dockerfile is published to
docker.io/elixircloud/krini, by CI for pushes to dev and by the release
workflow for releases:
| Tag | Points to |
|---|---|
X.Y.Z |
The release vX.Y.Z (also pre-releases, e.g. 0.1.0-rc1); never moved |
latest |
The highest stable release (no -alphaN, -betaN or -rcN) |
dev |
The newest commit that passed CI while it was the head of dev |
sha-<commit> |
That commit (full commit SHA) |
For deployments, prefer a release (X.Y.Z); dev follows the
development branch.
Images built before the rename carry the tag staging, which is no
longer updated: deployments that pull krini:staging must switch to
krini:dev.
The label org.opencontainers.image.version of a release image is its
version (e.g. 0.1.0), and of the images of dev
<version in package.json>-<branch>+<short commit SHA>, e.g.
0.1.0-dev+1a2b3c4.
Only a commit that is still the head of its branch when its checks have
passed is tagged: when commits are pushed in quick succession, the earlier
ones get no tags, and the branch tag can lag behind the branch until the
run of its newest commit passes. CI never sets latest: that tag is
reserved for releases. Deployments pull these images and update themselves
(e.g. with their own CD); the repository doesn't deploy anywhere itself.
Before CI tags an image, the commit passes lint, unit tests, type check,
build, a dependency audit and the end-to-end tests on its build, and
exactly the pushed digest passes a smoke test (non-root, read-only root
file system), the end-to-end tests again, now on the image started as it
is deployed (against mock services), and a scan for known
vulnerabilities (Trivy, failing on fixable critical and high findings). CI then attests its build provenance and signs it
with Sigstore keyless signing. The image also carries an SBOM and
BuildKit provenance. The release workflow builds release images afresh from
the tagged commit, which must have passed CI on dev, and checks, scans,
attests and signs them in the same way before it tags them.
Running the image¶
The image has no settings of its own: pass all environment variables of Configuration when the container starts, so that one image serves any deployment. For example:
docker run --rm -p 3000:3000 \
--read-only --tmpfs /tmp \
--env-file krini.env \
docker.io/elixircloud/krini:dev
- The server listens on port
3000(PORT) on all IPv4 interfaces; setLISTEN_HOSTNAME(e.g.::for IPv6) to change the interface. - It runs as the non-root user
bun(UID 1000) and can't change its own code. - It works with a read-only root file system: only
/tmpmust be writable (e.g. anemptyDirvolume in Kubernetes). Next.js caches, such as optimized images, go to/tmp/next-cache. - The image has a health check that requests the start page on
127.0.0.1; with aLISTEN_HOSTNAMEthat doesn't include the loopback interface, define your own health check (Kubernetes ignores the image's health check and uses its own probes).
Verifying images¶
Check the signature and the build provenance of an image before deploying it, e.g. with cosign and the GitHub CLI:
image=docker.io/elixircloud/krini:dev
cosign verify "${image}" \
--certificate-identity-regexp '^https://github\.com/elixir-cloud-aai/krini/\.github/workflows/ci\.yml@refs/heads/dev$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify "oci://${image}" --repo elixir-cloud-aai/krini
This also verifies sha-<commit> tags of images built since the rename;
for images built before it (the tag staging and their sha-<commit>
tags), use refs/heads/staging$ instead, or refs/heads/(staging|dev)$
for any sha-<commit> tag. Release images are signed by the release
workflow for their tag, e.g. for 0.1.0:
image=docker.io/elixircloud/krini:0.1.0
cosign verify "${image}" \
--certificate-identity 'https://github.com/elixir-cloud-aai/krini/.github/workflows/release.yml@refs/tags/v0.1.0' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify "oci://${image}" --repo elixir-cloud-aai/krini
Building the image¶
To build the image yourself:
The build uses no settings or .env* files (.dockerignore keeps them out
of the build context). The Bun version of both stages of the Dockerfile
must match packageManager in package.json, pinned by digest; CI checks
this.
Publishing from a fork¶
To publish images from a fork or for another organization, the repository needs:
- the variable
DOCKERHUB_ORG, the Docker Hub namespace (by defaultelixircloud), with a public repositorykriniin it, as the scan, the smoke test and the end-to-end tests pull the pushed digest without login; - the environment
dev-images, limited to the branchdev, with the secretsDOCKERHUB_LOGINandDOCKERHUB_TOKEN(a token that can push to that repository). The name is kept from when onlydevpublished images; - for releases, the environment
releasewith the same secrets (see Releasing). SetDOCKERHUB_ORGbefore pushing a test tag, as the workflows fall back toelixircloud.
To verify such images, use the fork's repository in the
--certificate-identity-regexp of cosign verify and in the --repo of
gh attestation verify.
Service configuration¶
Krini sends the user's access token to the TES and WES services from the
browser, and lists only services whose registry entry has an https URL.
That URL must be the base URL of the API, as in the GA4GH service registry,
e.g. https://tes.example.org/ga4gh/tes/v1: Krini appends the API paths
(e.g. /tasks) to it.
Only trusted services in the registry
Krini sends the token to every TES and WES service of the registry that
a user selects. Use a registry in which only administrators can
register services (in the Cloud Registry, remove the
register-services policy for regular users), so that nobody can add
a service that collects tokens. Filtering the list to verified
services in Krini is planned
(krini#40).
For the services to accept the token, the login provider and the services need the following configuration.
Scopes¶
Ensure your OIDC provider is configured to support the following scopes:
openid: Required for OpenID Connect authenticationprofile: Access to user profile informationemail: Access to user emailoffline_access: Required for refresh token support
Token type¶
The OIDC provider must issue access tokens as JWT (JSON Web Tokens) per RFC 9068, not opaque tokens: TES and WES services expect JWT access tokens for authentication.
Client allowlisting¶
TES and WES services must allowlist Krini's clientId of each LOGIN_PROVIDERS in their
authorization configuration: only allowlisted clients can use their access
tokens to authenticate with these services.
CORS configuration¶
Krini makes direct requests to WES (Workflow Execution Service) and TES (Task Execution Service) endpoints from the browser. You must configure CORS on your WES and TES services to allow requests from Krini's origin.
Required CORS headers¶
Your WES and TES services must return the following CORS headers for requests from Krini:
Access-Control-Allow-Origin: https://your-krini-domain.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true
Configuration example¶
For Nginx reverse proxy configurations:
location / {
add_header 'Access-Control-Allow-Origin' 'https://your-krini-domain.com' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
if ($request_method = 'OPTIONS') {
return 204;
}
proxy_pass http://backend;
}
For application-level CORS configuration (e.g., Express.js):
app.use(cors({
origin: 'https://your-krini-domain.com',
methods: ['GET', 'POST', 'PUT', 'DELETE'],
allowedHeaders: ['Authorization', 'Content-Type'],
credentials: true
}));
Multiple origins¶
If you need to support multiple Krini deployments (e.g., staging and production), configure your CORS to allow specific origins:
const allowedOrigins = [
'https://krini-staging.example.com',
'https://krini.example.com'
];
app.use(cors({
origin: (origin, callback) => {
if (!origin || allowedOrigins.includes(origin)) {
callback(null, true);
} else {
callback(new Error('Not allowed by CORS'));
}
},
credentials: true
}));
Environment variables¶
The Docker image contains no env files (.dockerignore excludes them) and
its build takes no settings. Pass the settings of
Configuration to the container when it starts, as
environment variables, for example:
- Docker:
docker run --env-file krini.env ..., withkrini.envkept outside the repository and the build context. Docker reads plainKEY=valuelines and doesn't strip quotes, so writePRIVACY_CONTROLLER=Example Institute, Example City, notPRIVACY_CONTROLLER="...". - Kubernetes or OpenShift: install the Helm chart, which passes the settings of its values to the container and
LOGIN_PROVIDERS(it contains each provider'sclientSecret) from aSecretof your own. Without the chart, use aConfigMapfor the non-secret settings and aSecretforLOGIN_PROVIDERS, referenced withenvFromorenv[].valueFromin the deployment.
Changing a setting needs a restart, not a new image; which settings reach the browser is described in Configuration.
Production considerations¶
- Cookies get the
Secureflag in production builds (next build, as in the Docker image);NODE_ENVis fixed when the app is built, so setting it at runtime changes nothing - Use HTTPS for all production deployments
- Configure
APP_ORIGINto your production domain - Store
LOGIN_PROVIDERSsecurely (e.g., using a secrets manager) — it contains the providers'clientSecretvalues - Rotate credentials regularly
- Set the
PRIVACY_*variables (see Privacy notice), so that the privacy notice at/privacynames who is responsible and how to reach them. - The notice's text is the same for every deployment. It describes what Krini itself does. Put anything specific to your deployment (purposes, legal basis, retention, rights) into your own notice and link it with
PRIVACY_NOTICE_URL. - Krini sets no cookies for visitors, unless they start a login or change the sidebar. Its cookies are listed in the notice, with their lifetimes. All except the sidebar setting are strictly necessary. Krini has no analytics, so it needs no consent banner. Krini's server reads the registry and checks the registered WES services, without user data. Browsers contact the selected TES and WES services directly, and the code editor of the workflow form loads a helper script from cdn.jsdelivr.net (from the Cloud Components); the notice says so. If you add anything that sets other cookies or tracks users, update the notice and add consent.
Security recommendations¶
- HTTPS only: Always deploy Krini behind HTTPS in production
- Secure cookies: Production builds set the
Secureflag on cookies automatically - Secret management: Never commit
.env.localor other env files (only.env.examplebelongs in the repository), never copy them into an image, and never expose secrets in client-side code - Origin validation: The logout endpoint validates requests against
APP_ORIGINto prevent CSRF - Token refresh: The
offline_accessscope enables silent token renewal, improving user experience - CORS restrictions: Configure CORS to only allow trusted origins