Skip to content

Commit

Permalink
docs: fix formatting (#2958)
Browse files Browse the repository at this point in the history
  • Loading branch information
chaoran-chen authored Oct 8, 2024
1 parent bec2a5f commit bc6b730
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 30 deletions.
45 changes: 16 additions & 29 deletions docs/src/content/docs/for-administrators/my-first-loculus.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,33 @@
---
title: "Tutorial: My first loculus"
title: 'Tutorial: My first loculus'
description: Experimenting with a Loculus interface running in a local mini Kubernetes cluster
---


This tutorial will guide you through setting up a test instance for Loculus locally, running on a mini Kubernetes cluster. You'll learn how to install dependencies, deploy Loculus, configure a custom organism, and submit sample data. By the end, you'll have a Loculus database running on your machine, providing hands-on experience of how things work (but the setup will not be suitable for production use).


:::note[System requirements]
This tutorial is intended for Linux. It has been tested on a fresh Ubuntu installation running on a DigitalOcean droplet (though you will find it simpler if you are able to run it locally.)

Loculus has considerable resource requirements. We would recommend at least 6 GB of RAM and 6 cores for even this test deployment.
:::


## Setting up the dependencies


For this example we will be deploying Loculus using its [Helm](https://helm.sh/) chart, which is deployed on a Kubernetes cluster. There are many different ways of installing Kubernetes, including on managed Cloud Services, but for these purposes we will run Kubernetes on our own machine, using [k3d](https://k3d.io/), which relies on [Docker](https://www.docker.com/).

#### Docker
#### Docker

First, if we don't have Docker installed, we need to install it. You should do this by following the instructions on the [Docker website](https://docs.docker.com/get-started/get-docker/).


#### K3d
#### K3d

Next, we need to install [k3d](https://k3d.io/), which is a lightweight wrapper to run [K3s](https://k3s.io/) (a lightweight Kubernetes distribution) in Docker. To install k3d, run the following command:

```bash
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
```


#### kubectl
#### kubectl

To manage this cluster we will need [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/), which is the Kubernetes command-line tool. You can do this by running the following commands:

Expand All @@ -44,7 +38,7 @@ sudo mv kubectl /usr/local/bin/

```

#### Helm
#### Helm

We deploy Loculus we also need [Helm](https://helm.sh/), which is a package manager for Kubernetes. You can do this by running the following commands:

Expand All @@ -54,7 +48,6 @@ chmod 700 get_helm.sh
./get_helm.sh
```


## Our first Loculus instance

Now we need to get the Loculus Helm chart and some helper scripts. You can do this by cloning the Loculus repository:
Expand All @@ -64,8 +57,8 @@ git clone https://github.com/loculus-project/loculus.git
cd loculus
```


### Creating a cluster

We have a wrapper script which can help with creating a cluster with the correct ports forwarded and to ensure some useful Helm charts get installed. To create a cluster, run the following command:

```bash
Expand All @@ -82,7 +75,6 @@ Now we can install Loculus using the Helm chart. To do this, run the following c
helm install loculus ./kubernetes/loculus --set environment=local --set branch=latest --set disableIngest=true --set disableEnaSubmission=true
```


#### Checking the status

That command may complete relatively quickly, but it may take a few minutes for the Loculus pods to be fully running. You can check the status of the pods by running the following command:
Expand All @@ -91,7 +83,7 @@ That command may complete relatively quickly, but it may take a few minutes for
kubectl get pods
```

The limiting factor in the pods starting is typically the `loculus-keycloak` pod.
The limiting factor in the pods starting is typically the `loculus-keycloak` pod.

Until it starts, other pods will crash because they need it for authentication.

Expand All @@ -114,7 +106,7 @@ Let's create a new configuration.
Create a new file (for now we will call it `custom_values.yaml` and it can be in your current working directory) with the following content:

```yaml
name: "My awesome database"
name: 'My awesome database'
```
Now we can "upgrade" the existing Loculus with this configuration:
Expand All @@ -133,12 +125,13 @@ Loculus ships with some default organisms, but you probably want to overwrite th

Let's edit the `custom_values.yaml` file to the following:

<!-- prettier-ignore-start -->
```yaml
name: "Angelovirus DB"
name: 'Angelovirus DB'
organisms:
asterovirus:
schema:
organismName: "Angelovirus"
organismName: 'Angelovirus'
metadata:
- name: country
type: string
Expand All @@ -156,28 +149,27 @@ organisms:
- version: 1
image: ghcr.io/loculus-project/preprocessing-nextclade
args:
- "prepro"
- 'prepro'
configFile:
log_level: DEBUG
genes: []
batch_size: 100
referenceGenomes:
nucleotideSequences:
- name: "main"
sequence: "NNN" # We are not performing alignment here, so this sequence doesn't matter
- name: 'main'
sequence: 'NNN' # We are not performing alignment here, so this sequence doesn't matter
genes: []
createTestAccounts: true
```
<!-- prettier-ignore-end -->
Now we can upgrade the Loculus installation again:
```bash
helm upgrade loculus ./kubernetes/loculus --set environment=local --set branch=latest --set disableIngest=true --set disableEnaSubmission=true -f custom_values.yaml
```


Because we have enabled the `createTestAccounts` option, we need to delete the existing keycloak database to ensure that the test users are added.
Because we have enabled the `createTestAccounts` option, we need to delete the existing keycloak database to ensure that the test users are added.

First we need to run `kubectl get pods` to get the name of the keycloak pod, which will be something like `loculus-keycloak-database-665b964c6b-gm9t5` (but with the random string at the end being different).

Expand All @@ -193,10 +185,8 @@ If you struggled with deleting the pod, an alternative approach would be to dele

While that's getting ready, let's create some data to submit.


First let's make our sequence file, which we might name `sequences.fasta`:


```txt
>sample1
ATGGGATTTTGGCATATATATACGA
Expand Down Expand Up @@ -226,7 +216,6 @@ You can then go to `Submit`. You will be prompted to create a submitting group.
To successfully create a submitting group you will need to be able to access `127.0.0.1` on port `8079` (if you are running this on a remote machine you will need to set up port forwarding for this port too!).
:::


Once you have created a submitting group, you can submit your data. You will need to upload the `sequences.fasta` and `metadata.csv` files. You can then select the organism you created earlier (`Angelovirus`) and submit the data.

You should find that they appear on your Review page and you can choose to release them. If you wait a minute and then refresh the Search page you should find your sequences have appeared! **🎉 We've released the first data for our new database!**
Expand All @@ -239,8 +228,6 @@ When you are done with experimenting, you can delete the cluster with the follow
./deploy.py cluster --delete
```



:::caution

While the pattern that was described in this tuorial is a good way to get started with Loculus, it is not suitable for production use. For a production deployment, you should use a production focused cluster -- either one from a managed service like Vultr, Digital Ocean, AWS, GCP, Azure, or more -- or a self managed cluster, which you can run using [k3s](https://k3s.io/), which is related to k3d.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,3 @@ If you are looking for a software to manage sequencing data and would like to kn
**GenSpectrum** uses Loculus internally to store sequencing data and power its interactive dashboards for analyzing and tracking variants and mutations of viruses. It is currently under development and will be released soon.

If you also host a Loculus instance and would like it to be added to this list, please reach out!

0 comments on commit bc6b730

Please sign in to comment.