Helm chart config

Note

The config structure has not been finalized and may change rapidly until Loculus 1.0 is officially released (see 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

Field	Type	Default	Description
name	String	"Loculus"	The name of the Loculus instance
logo	Object		Configuration for the logo
logo.url	String		URL path to the logo image file
logo.width	Integer	100	Width of the logo in pixels
logo.height	Integer	100	Height of the logo in pixels
accessionPrefix	String	"LOC_"	Prefix used for accession numbers
environment	local, server	"server"	Deployment environment. local for development, server for production
host	String		Hostname where Loculus will be accessible
bannerMessage	String	"This is a demonstration environment. It may contain non-accurate test data and should not be used for real-world applications. Data will be deleted regularly."	Banner message (as HTML) to display at the very top of the page
welcomeMessageHTML	String, Null		A custom welcome message to be shown on the landing page
additionalHeadHTML	String		Additional HTML to inject into the of pages
createTestAccounts	Boolean		If true, creates the users testuser and superuser
robotsNoindexHeader	Boolean		If true, adds a noindex header to prevent search engine indexing
seqSets	Object
seqSets.enabled	Boolean		Enable/disable SeqSets. If false, seqSets.crossRef can be omitted.
seqSets.crossRef	Object		Configuration for CrossRef integration. Set to null to disable CrossRef integration (you can still use SeqSets without CrossRef DOIs).
seqSets.crossRef.DOIPrefix	String		The DOI prefix for SeqSets
seqSets.crossRef.endpoint	String		The API endpoint for CrossRef
seqSets.crossRef.databaseName	String		The database name for CrossRef
seqSets.crossRef.email	String		The email address associated with the CrossRef account
seqSets.crossRef.organization	String		The organization name for CrossRef
seqSets.crossRef.hostUrl	String		The host URL for CrossRef callbacks
gitHubMainUrl	String	"https://github.com/loculus-project/loculus"	The link that the GitHub icon in the footer points to
sequenceFlagging.github	Object		Settings to enable sequence reporting via GitHub. If set, a button will be enabled on sequence details views to report issues with a sequence.
dataUseTerms.enabled	Boolean		Whether this Loculus instance handles data use terms.
dataUseTerms.urls.open	String		A URL describing the open data use terms.
dataUseTerms.urls.restricted	String		A URL describing the restricted data use terms.

Website Settings

Field	Type	Default	Description
website	Object		Website specific setting
website.websiteConfig	Object		Settings for the website_config.json
website.websiteConfig.enableLoginNavigationItem	Boolean	true	Whether the website should show the login button.
website.websiteConfig.enableSubmissionNavigationItem	Boolean	true	Whether the website should show "Submit" link in the top navigation bar.
website.websiteConfig.enableSubmissionPages	Boolean	true	Whether to completely disable submission related pages. Setting this to false is useful when hosting Loculus for analysis-only purposes.
website.runtimeConfig.public	Object		Settings for the public section of the runtime_config.json
website.runtimeConfig.public.backendUrl	String		Overwrite the URL where the client-side website code expects the Loculus backend
website.runtimeConfig.public.keycloakUrl	String		Overwrite the URL where the client-side website code expects the Keycloak
website.runtimeConfig.public.lapisUrlTemplate	String		Overwrite the URLs where the client-side website code expects the LAPIS instances. Must contain %organism% as a placeholder.

User registration and authentication

Field	Type	Default	Description
auth	Object		User authentication (Keycloak settings)
auth.smtp	Object		Configuration for email sending
auth.smtp.host	String		SMTP server hostname
auth.smtp.port	Integer		SMTP server port
auth.smtp.user	String		SMTP username for authentication
auth.smtp.replyTo	String		Reply-to email address for sent emails
auth.smtp.from	String		From email address for sent emails
auth.smtp.envelopeFrom	String		Envelope from address for sent emails
auth.verifyEmail	Boolean	true	If true, requires email verification for new accounts
auth.resetPasswordAllowed	Boolean	true	If true, allows users to reset their passwords
auth.registrationAllowed	Boolean	true	If true, allows users to register new accounts in Keycloak.
insecureCookies	Boolean	false	If true, allows insecure cookies.
registrationMessage	String	"You must agree to the <a href='http://main.loculus.org/terms'>terms of use</a>."	Message displayed during user registration, typically including terms of service.

Database deployments

Field	Type	Default	Description
runDevelopmentMainDatabase	Boolean	true	If true, runs a development database within the cluster.
runDevelopmentKeycloakDatabase	Boolean	true	If true, runs a development Keycloak database within the cluster.
developmentDatabasePersistence	Boolean	true	If true, makes the database on the argocd preview persistent.

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

Services

Field	Type	Default	Description
disableWebsite	Boolean	false	If true, disables the frontend website deployment.
disableBackend	Boolean	false	If true, disables the backend API deployment.
disablePreprocessing	Boolean	false	If true, disables preprocessing pipelines.
disableIngest	Boolean	false	If true, disables ingestion services.
disableEnaSubmission	Boolean	false	If true, disables ENA (European Nucleotide Archive) submission service.
customWebsiteImage	String		Optional custom Docker image for the website.

Organism Configuration

Field	Type	Default	Description
organisms	Object		An object where the keys are the organism IDs and values are an Organism (type)
lineageSystemDefinitions	Object		An object where the keys are the lineage system names and values are links to lineage system definition files per pipeline version (See Lineage system definitions)

Lineage system definitions

Here’s an example of a lineageDefinitions section:

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

Field	Type	Default	Description
lineageSystemDefinitions.<name>	Object		A map from pipeline versions to file URLs.
lineageSystemDefinitions.<name>.<pipelineVersion>	String		The URL to the lineage defintion file for that lineage system and that pipeline version.

Organism (type)

Each organism object has the following fields:

Field	Type	Default	Description
schema	Object		Object of type organism schema
preprocessing	Array		Array of Preprocessing (type).
ingest	Object		Object of type Ingest
referenceGenomes.nucleotideSequences	Array		Array of Nucleotide sequence (type)
referenceGenomes.genes	Array		Array of Gene (type)

Organism schema (type)

Field	Type	Default	Description
organismName	String		Display name for the organism
image	String		URL to an image that will be shown on the landing page
loadSequencesAutomatically	Boolean	true	Whether sequences be loaded automatically on the sequence details page , rather than users having to press a button to do so. (For small genomes, this should probably be true.)
submissionDataTypes.consensusSequences	Boolean	true	If false, the submission form will not allow submission of consensus sequences (i.e. the sequences file must be omitted). All consensus sequence related parts on the website will be hidden.
description	String
metadata	Array		Array of Metadata fields (type) associated with the organism.
metadataTemplate	Array		Array of strings. Which input fields to add to the downloadable metadata template on the submission and revision page.
earliestReleaseDate	Object		Configuration object for enabling and configuring the earliestReleaseDate metadata field. For each version of an accession, the earliestReleaseDate is calculated as the earliest date of the internal release date, the dates in the configured externalFields and the value from the previous version of the accession (if there is one). This can be used when having a mix of sequences imported from other databases, as well as sequences released first in this Loculus instance, to have a field that shows the earliest release date regardless of where the sequence was first released.
earliestReleaseDate.enabled	Boolean		Whether to enable the earliestReleaseDate metadata field.
earliestReleaseDate.externalFields	Array		Field names to use when calculating the earliest release date. The fields need to be nullable strings formated with yyyy-mm-dd.
website	Object		Configuration for how the organism data is displayed on the website
website.tableColumns	Array		Columns to display in the browse table
website.defaultOrderBy	String		Default column to sort the browse table
website.defaultOrder	ascending, descending		Default order direction.
silo	Object		Configuration regarding the SILO database engine
silo.dateToSortBy	String		Name of a field of type date. This might speed up date range searches on this field and improve sequence compression.
silo.partitionBy	String

Metadata field (type)

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

Field	Type	Default	Description
name	String		Key used across app to refer to this field.
displayName	String		Name displayed to users.
type	string, int, float, number, date, boolean, authors	"string"
header	String		Grouping of fields in sequence details UI.
required	Boolean		Whether the field is required by backend.
desired	Boolean		Whether the field is a desired input field for submitters.
definition	String		Definition of input field for submitters.
guidance	String		Guidance for submitters on filling in input field.
noInput	Boolean		Whether a field with this name is expected as possible input, and so should be included in the metadata template and as a form field. (If set to true it will not be included).
generateIndex	Boolean		Whether the field should be indexed for search. This is only allowed for string fields and facilitates faster filters. It is recommended if the number of different values is rather small.
columnWidth	Number		The minimum column width for this field on the search table.
order	Number		Order for the column in the search table, lower first.
autocomplete	Boolean		Whether autocomplete should be offered for the field. This is only allowed for string fields and probably generateIndex should be true.
enableSubstringSearch	Boolean		If true, search results will contain results that contain the given value as a substring. If false (the default), only exact matches will be returned. This only works for string fields, and you cannot also enable autocomplete.
rangeSearch	Boolean		If true, enables range search for numeric fields.
rangeOverlapSearch	Object		Config settings for enabling range overlap search.
rangeOverlapSearch.rangeId	String		The range that this field belongs to. Two fields (the upper and lower bound) need to be defined with the same range ID.
rangeOverlapSearch.rangeDisplayName	String		The display name of the range.
rangeOverlapSearch.bound	lower, upper		Whether this field is the lower or upper bound of the range.
initiallyVisible	Boolean		If true, the field is initially visible in the UI.
hideOnSequenceDetailsPage	Boolean		If true, hides the field on the sequence details page.
hideInSearchResultsTable	Boolean		If true, hides the field in the search results table (and makes it impossible to show).
perSegment	Boolean		Whether this is a metadata field that should exist for each segment. If so fields will be created as fieldName_A, fieldName_B in the case of an organism with segments A and B.
customDisplay	Object		Custom display settings for the field on the sequence details page.
customDisplay.type	String
customDisplay.url	String
ontology_id	String
example	String, Number		Example value for the field.
ingest	String		Which NCBI field to map to this field.
preprocessing	Object		The values of this field will be added to the preprocessing pipeline config file and the available values depend on the chosen pipeline. For the Nextclade pipeline, please see here.
lineageSystem	String		Use this on string fields that contain lineages, if you want to enable searches that can include sublineages. The value needs to be a lineage system that is defined under the lineageSystemDefinitions key.

Preprocessing (type)

Field	Type	Default	Description
version	Integer		Version of the preprocessing pipeline
image	String		Docker image for the preprocessing pipeline
args	Array		Array of Strings. Arguments passed to the preprocessing pipeline.
configFile	Object		Fields that should be added to the preprocessing pipeline config file.

The values for args and configFile depend on the used preprocessing pipeline. For the Nextclade preprocessing pipeline, please see here.

Ingest (type)

Field	Type	Default	Description
image	String	"ghcr.io/loculus-project/ingest"	Docker image for the ingest pipeline
configFile	Object		Fields that should be added to the ingest pipeline config file

The values for configFile depend on the used preprocessing pipeline. For our ingest pipeline which downloads data from NCBI GenBank using NCBI Datasets, the config file needs to contain the taxon_id of the organism and additionally, if the organism is multi-segmented, it requires a list of segment names (nucleotide_sequences) and the nextclade_dataset that can be used for segment identification and alignment.

NucleotideSequence (type)

Field	Type	Default	Description
name	String		Name of the sequence
sequence	String
insdcAccessionFull	String		INSDC accession of the sequence

Gene (type)

Field	Type	Default	Description
name	String		Name of the sequence.
sequence	String