Skip to content

Commit

Permalink
feat(docs): reference how to start LAPIS and SILO #569 #570
Browse files Browse the repository at this point in the history
  • Loading branch information
fengelniederhammer committed Jan 16, 2024
1 parent fb15c1a commit 0e48240
Show file tree
Hide file tree
Showing 4 changed files with 123 additions and 1 deletion.
8 changes: 8 additions & 0 deletions lapis2-docs/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
],
},
{
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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>`.
:::
8 changes: 7 additions & 1 deletion lapis2-docs/tests/docs.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down

0 comments on commit 0e48240

Please sign in to comment.