diff --git a/lapis2-docs/astro.config.mjs b/lapis2-docs/astro.config.mjs index c7b2ab75..7e195453 100644 --- a/lapis2-docs/astro.config.mjs +++ b/lapis2-docs/astro.config.mjs @@ -155,6 +155,14 @@ export default defineConfig({ label: 'Reference Genomes', link: '/maintainer-docs/references/reference-genomes', }, + { + label: 'Starting SILO and LAPIS', + link: '/maintainer-docs/references/starting-silo-and-lapis', + }, + { + label: 'Preprocessing', + link: '/maintainer-docs/references/preprocessing', + }, ], }, { diff --git a/lapis2-docs/src/content/docs/maintainer-docs/references/preprocessing.mdx b/lapis2-docs/src/content/docs/maintainer-docs/references/preprocessing.mdx new file mode 100644 index 00000000..0ebc0e21 --- /dev/null +++ b/lapis2-docs/src/content/docs/maintainer-docs/references/preprocessing.mdx @@ -0,0 +1,11 @@ +--- +title: Preprocessing +description: Reference on the SILO preprocessing +--- + +TODO #565 + +- preprocessing config. Has defaults set in Docker. Only set what you need, leave the rest to the defaults +- input format of data + +## Preprocessing config diff --git a/lapis2-docs/src/content/docs/maintainer-docs/references/starting-silo-and-lapis.mdx b/lapis2-docs/src/content/docs/maintainer-docs/references/starting-silo-and-lapis.mdx new file mode 100644 index 00000000..a3c49a26 --- /dev/null +++ b/lapis2-docs/src/content/docs/maintainer-docs/references/starting-silo-and-lapis.mdx @@ -0,0 +1,97 @@ +--- +title: Starting SILO and LAPIS +description: Reference on how to start the SILO and LAPIS applications +--- + +:::note +The [corresponding tutorial](/maintainer-docs/tutorials/start-lapis-and-silo) +shows an example step by step. +This page aims to provide a full reference. +::: + +## Starting SILO + +SILO can be started in two modes: + +- `preprocessing`: Starts the SILO preprocessing that prepares the data for the SILO API server. +- `api`: Starts the SILO API server that responds to SILO queries. + +We provide Docker images for SILO with the name: `ghcr.io/genspectrum/lapis-silo`. +Those images can be used to start SILO in both modes. + +### Starting the SILO preprocessing + +To start the SILO preprocessing you need to provide the argument `--preprocessing`. +SILO will then start reading the input data, process it +and terminate after the result is written to the output directory. + +Optionally, you can specify: + +- `--preprocessingConfig`: + The path to the [preprocessing config](/maintainer-docs/references/preprocessing#preprocessing-config) file that SILO should use, + e.g. `~/LAPIS/preprocessing_config.yaml` +- `--databaseConfig`: + The path to the [database config](/maintainer-docs/references/database-configuration) file that SILO should use, + e.g. `~/LAPIS/database_config.yaml`. + +If those parameters are not provided, SILO will try to read the files from its current working directory. + +#### Starting the SILO preprocessing with Docker + +You only have to pass the argument `--preprocessing` to the Docker container. +The image is constructed with defaults in a way that you only need to mount the data to the correct locations: + +- the preprocessing config to `/app/preprocessing_config.yaml`, +- the database config to `/app/database_config.yaml`, +- the data to `/preprocessing/input`, +- the output directory to `/preprocessing/output`. + +### Starting the SILO API + +To start the SILO API server you need to provide the argument `--api`. +It will start a web server that listens to port 8081. + +The SILO API will read data from a directory that can be specified (in descending order of prevalence) via: + +- a program argument `--dataDirectory`, +- YAML file `./runtime_config.yaml` (in SILO's working directory) with the key `dataDirectory`, +- the default value `./output/` (in SILO's working directory). + +The database config does not need to be provided. +It is contained in the compiled output of the preprocessing. + +#### Starting the SILO API with Docker + +You only have to pass the argument `--api` to the Docker container. +The image is constructed with a runtime config file that sets the data directory to `/data`, +i.e. you only need to mount the result of the preprocessing to `/data`. + +## Starting LAPIS + +To start LAPIS you need to provide the following parameters: + +- `--silo.url`: The URL where SILO is running, e.g. `http://localhost:8081`. +- `--lapis.databaseConfig.path`: + The path to the [database config](/maintainer-docs/references/database-configuration) file that LAPIS should use, + e.g. `~/LAPIS/database_config.yaml`. +- `--referenceGenomeFilename`: + The path to the [reference genomes](/maintainer-docs/references/reference-genomes) file that LAPIS should use, + e.g. `~/reference_genomes.json`. + This can alternatively be passed via the environment variable `REFERENCE_GENOME_ENV_VARIABLE_NAME`. + The parameter takes precedence over the environment variable. + +LAPIS listens to port 8080. + +#### Starting LAPIS with Docker + +We provide Docker images for LAPIS with the name: `ghcr.io/genspectrum/lapis-v2`. + +The provided Docker images already contain reasonable default values for + +- the `lapis.databaseConfig.path` parameter: `/workspace/database_config.yaml`, +- the `REFERENCE_GENOME_ENV_VARIABLE_NAME` environment variable: `/workspace/reference_genomes.json`. + +:::note +You simply need to mount the config files to those locations in the container +and start the container with `--silo.url=`. +::: diff --git a/lapis2-docs/tests/docs.spec.ts b/lapis2-docs/tests/docs.spec.ts index 4a3d84fa..2243cd9e 100644 --- a/lapis2-docs/tests/docs.spec.ts +++ b/lapis2-docs/tests/docs.spec.ts @@ -35,7 +35,13 @@ const architecturePages = [ 'Glossary', ]; -const maintainerDocsPages = ['Database Configuration', 'Reference Genomes', 'Start LAPIS and SILO']; +const maintainerDocsPages = [ + 'Database Configuration', + 'Reference Genomes', + 'Starting SILO and LAPIS', + 'Preprocessing', + 'Start LAPIS and SILO', +]; const pages = [ ...gettingStartedPages,