---
title: 'Helm chart config'
description: A reference of config fields for the Loculus Helm chart
---

import SchemaDocs from '../../../components/SchemaDocs.astro';

:::note
The config structure has not been finalized and may change rapidly until Loculus 1.0 is
officially released (see [current state and roadmap](../../introduction/current-state-and-roadmap/)).
In the meantime, this reference might also not be fully accurate or complete.
:::

The configuration for the Helm chart is provided as a YAML file. It has the following fields:

## General Settings

<SchemaDocs group='general' fieldColumnClass='w-56' />

## Website Settings

<SchemaDocs group='website' fieldColumnClass='w-56' />

## User registration and authentication

<SchemaDocs group='auth' fieldColumnClass='w-56' />

## Database deployments

<SchemaDocs group='db' fieldColumnClass='w-72' />

For production environments, these should always be set to false.
Instead, external managed databases should be used.

## S3 deployments

<SchemaDocs group='s3' fieldColumnClass='w-72' />

## Services

<SchemaDocs group='services' fieldColumnClass='w-48' />

### Read-only mode

Setting `readOnlyMode: true` at the top level of `values.yaml` puts the instance
into a read-only state. When enabled:

- The backend rejects every mutating request (`POST`, `PUT`, `PATCH`, `DELETE`)
  with `503 Service Unavailable` and a problem-detail body explaining that the
  instance is in read-only mode. `GET` requests continue to work.
- The website hides the Login and Submit navigation items, disables the
  submission pages (they return 404), skips the Keycloak redirect on pages that
  would otherwise enforce login (they render a read-only notice instead), and
  shows a banner informing users the instance is read-only.

This flag is intended for migrations, archival instances, and maintenance
windows. It defaults to `false`.

## SILO Configuration

<SchemaDocs group='silo' fieldColumnClass='w-48' />

## Organism Configuration

<SchemaDocs group='organism-conf' fieldColumnClass='w-48' />

### Lineage system definitions

Here's an example of a `lineageDefinitions` section:

```yaml
lineageSystemDefinitions:
  pangoLineage: # Lineage name to use in metadata fields
    1: https://example.org/lineage_defintions_v1.yaml # Definition per pipeline version
    2: https://example.org/lineage_defintions_v2.yaml
  myLineage:
    1: ...
```

<SchemaDocs group='lineage-system-definitions' fieldColumnClass='w-48' />

Note: Lineages should be determined by the preprocessing pipeline and not the user, set the lineage field to `noInput: true` to reflect this or alternatively only allow users to submit valid lineage values by adding an `options` list.

### Hierarchical filter sources

For metadata fields whose values form a hierarchy that's resolved at SILO import
time (rather than fetched as a static file per pipeline version), set
`hierarchicalFilter: <URL>`, where URL is the URL of the service that will create the
hierarchical file for SILO. The importer collects observed
values for the field, sends them to that service, and writes the returned YAML
into SILO's input directory as `<MetadataName>.yaml`.

### Organism (type)

Each organism object has the following fields:

<SchemaDocs group='organism' fieldColumnClass='w-48' />

### Organism schema (type)

<SchemaDocs group='schema' fieldColumnClass='w-60' />

### Metadata field (type)

Definition of metadata fields for sequence entries of an organism, for example the collection date and location of a sample.

<SchemaDocs group='metadata' fieldColumnClass='w-56' />

#### Custom display

Use the optional `customDisplay` object on a metadata field to change how the
value appears on the sequence details page. The object can contain
`type`, `url`, `html`, `value`, `linkMenuItems` and `displayGroup` properties. The `type`
property controls the behaviour:

- `link` – open the value as a hyperlink using the `url` where `__value__` is
  replaced by the actual value.
- `linkWithMenu` – display the value as a hyperlink with a dropdown menu for
  multiple link options. Requires `linkMenuItems` array with objects containing
  `name` and `url` properties. The first item is used as the default/primary link
  that opens when clicking the value directly.
- `badge` – show mutation lists as coloured badges (requires `value`).
- `htmlTemplate` – replace `__value__` in the provided `html` string and render
  the resulting HTML snippet.
- `percentage` – display numeric values as percentages.
- `dataUseTerms` – show the value together with a data use terms history modal.
- `submittingGroup` – interpret the value as JSON with group details and link to
  the group page.
- `fileList` – interpret the value as a JSON list of files and show them as
  download links.

When `displayGroup` is provided, all entries with the same group are collapsed
into a single row.

##### Example: linkWithMenu for INSDC accessions

```yaml
- name: insdcAccessionFull
  displayName: INSDC accession
  customDisplay:
    type: linkWithMenu
    linkMenuItems:
      - name: View in NCBI
        url: 'https://www.ncbi.nlm.nih.gov/nuccore/__value__'
      - name: View in ENA
        url: 'https://www.ebi.ac.uk/ena/browser/view/__value__'
      - name: View in DDBJ
        url: 'https://www.ddbj.nig.ac.jp/entry/__value__'
  header: 'INSDC'
```

### Preprocessing (type)

<SchemaDocs group='preprocessing' fieldColumnClass='w-28' />

The values for `args` and `configFile` depend on the used preprocessing pipeline.

#### Nextclade Preprocessing Pipeline ConfigFile (type)

<SchemaDocs group='nextcladePipelineConfigFile' fieldColumnClass='w-28' />

##### Nextclade Preprocessing Pipeline Sequence and Dataset Objects (type)

<SchemaDocs group='nextcladeSegment' fieldColumnClass='w-28' />

For more details on the Nextclade preprocessing pipeline, please see
[here](../../for-administrators/existing-preprocessing-pipelines/#nextclade-based-pipeline).

### Ingest (type)

<SchemaDocs group='ingest' fieldColumnClass='w-28' />

The values for `configFile` depend on the used preprocessing pipeline.

#### Ingest ConfigFile (type)

For [our ingest pipeline](https://github.com/loculus-project/loculus/tree/main/ingest) we require the following fields:

<SchemaDocs group='ingestPipelineConfigFile' fieldColumnClass='w-28' />

### Reference Genome (type)

<SchemaDocs group='reference-genome' fieldColumnClass='w-48' />

### NucleotideSequence (type)

<SchemaDocs group='nucleotide-sequence' fieldColumnClass='w-48' />

### Gene (type)

<SchemaDocs group='gene' fieldColumnClass='w-48' />

### Image spec (type)

<SchemaDocs group='image' fieldColumnClass='w-48' />
