feat(docs): reference how to start LAPIS and SILO #569 #570

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',
+                                },
                             ],
                         },
                         {

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

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=<your SILO URL>`.
+:::

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,