Setup LAPIS for monkeypox

In this tutorial, you will setup a LAPIS instance for monkeypox. You will learn:

  • how import data into LAPIS’ database

  • how to start the API server

Note: This setup is only for testing/demonstration purposes and not recommended for productive use.


  • A working installation of Docker and basic familiarity with using Docker

Data download and alignment

To get started, LAPIS needs some metadata, the unaligned sequences and, if available, aligned sequences. For monkeypox, example data is available in Nextstrain’s monkeypox repository. Please download the metadata.tsv and sequences.fasta. They are already correctly formatted.

Next, the sequences should be aligned. It is possible to start LAPIS without an alignment (in that case, create an empty aligned.fasta) but in order to filter and aggregate by mutations, an alignment is needed. You can use Nextclade version 2 to obtain an alignment. Open the website, select “Monkeypox” as the pathogen, select the sequences.fasta file that you downloaded and click an the “Run” button. It can take a few moments until the sequences are analyzed. Once it has finished, you can click on the download symbol on the top right and download the nextclade.aligned.fasta file. Rename the file to aligned.fasta.

Place the files metadata.tsv, sequences.fata and aligned.fasta into the same directory.

    |-- metadata.tsv
    |-- sequences.fasta
    |-- aligned.fasta

Initialize database

LAPIS uses a PostgreSQL database (version 14+). An easy option to set up a database is to use the postges Docker image. First, download the SQL scripts in from here and place them in the same directory. Open 01_users.sql and set the passwords for the users.

    |-- 01_users.sql
    |-- 02_init.sql
    |-- 03_transform_and_merge.sql

Execute the following command to start the database. Change the password for the postgres user in the command.

docker network create -d bridge lapis_network

docker run -d \
    --name lapis_db \
    --net lapis_network \
    -e POSTGRES_PASSWORD=<missing> \
    -v /path/to/db-scripts:/docker-entrypoint-initdb.d \

Data import

First, create a file lapis-proc-config.yml with the following content (please fill in the password):

  host: lapis_db
  port: 5432
  dbname: postgres
  username: lapis_proc
  password: <missing>
  schema: public
workdir: /data
maxNumberWorkers: 20

Then, execute the following command:

docker run --rm \
    --name lapis_proc \
    --net lapis_network \
    --entrypoint java \
    -v /path/to/lapis-proc-config.yml:/app/lapis-config.yml \
    -v /path/to/data:/data \ \
        -jar /app/lapis.jar \
        --config /app/lapis-config.yml \
        Lapis --update-data load-mpox,transform-mpox,switch-in-staging

API server

To start the API server, create a file lapis-api-config.yml with the following content (please fill in the password):

  host: lapis_db
  port: 5432
  dbname: postgres
  username: lapis_api
  password: <missing>
  schema: public
cacheEnabled: false
apiOpennessLevel: OPEN

Then, execute the following command:

docker run --rm \
    --name lapis_api \
    --net lapis_network \
    -v /path/to/lapis-api-config.yml:/app/lapis-config.yml \
    -p \

Wait half a minute and then open http://localhost:2345/v1/sample/aggregated in your browser.