From 49fde9d8e15f11caa91207a02b0caa394a32cdfe Mon Sep 17 00:00:00 2001 From: Chaoran Chen Date: Fri, 9 Aug 2024 17:42:47 +0200 Subject: [PATCH] docs: improve getting started for administrators (#2406) Co-authored-by: Anna (Anya) Parker <50943381+anna-parker@users.noreply.github.com> --- docs/astro.config.mjs | 8 +++-- .../for-administrators/getting-started.md | 34 +++++++++++++++++++ .../setup-with-kubernetes.md} | 4 +-- .../user-administration.md | 0 docs/src/content/docs/index.mdx | 2 +- .../introduction/current-state-and-roadmap.md | 8 +++++ 6 files changed, 50 insertions(+), 6 deletions(-) create mode 100644 docs/src/content/docs/for-administrators/getting-started.md rename docs/src/content/docs/{guides/getting-started.md => for-administrators/setup-with-kubernetes.md} (99%) rename docs/src/content/docs/{guides => for-administrators}/user-administration.md (100%) create mode 100644 docs/src/content/docs/introduction/current-state-and-roadmap.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index e11e666519..43e8d89016 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -21,15 +21,17 @@ export default defineConfig({ label: "Introduction", items: [ { label: "What is Loculus?", link: "/introduction/what-is-loculus/" }, + { label: "Current state and roadmap", link: "/introduction/current-state-and-roadmap/" }, { label: "Glossary", link: "/introduction/glossary/" }, { label: "System overview", link: "/introduction/system-overview/" }, ], }, { - label: "Guides", + label: "For administrators", items: [ - { label: "Getting started", link: "/guides/getting-started/" }, - { label: "User administration", link: "/guides/user-administration/" }, + { label: "Getting started", link: "/for-administrators/getting-started/" }, + { label: "Setup with Kubernetes", link: "/for-administrators/setup-with-kubernetes/" }, + { label: "User administration", link: "/for-administrators/user-administration/" }, ], }, { diff --git a/docs/src/content/docs/for-administrators/getting-started.md b/docs/src/content/docs/for-administrators/getting-started.md new file mode 100644 index 0000000000..fa148d466d --- /dev/null +++ b/docs/src/content/docs/for-administrators/getting-started.md @@ -0,0 +1,34 @@ +--- +title: Getting started +description: How to deploy a Loculus instance +--- + +This section of the documentation is for administrators of a Loculus instance. Below, we describe how you can set up a new instance. + +## Before you start + +Although Loculus is in principle stable and can be used in production, we plan to refactor the schema of the configuration files and the API of the backend server. This means that if you set up an instance at the moment, future updates will require significant effort. Additionally, until we have finalized the configuration schemas and APIs, **the documentation will be very sparse**. You can read more about the [current state of Loculus](../../introduction/current-state-and-roadmap). + +As presented in the [system overview](../../introduction/system-overview) (which we recommend reading), Loculus consists of numerous sub-services which need to be configured and wired together. All services are available as Docker images. For local development and the preview instances, we use Kubernetes and Helm for deployment but it is also possible to deploy Loculus without Kubernetes. + +## With Kubernetes + +Here is a [guide to deploy Loculus with Kubernetes](../setup-with-kubernetes). + +## With Docker Compose + +We do not have a guide to deploy Loculus with Docker Compose at the moment but you can check out the [GenSpectrum configuration](https://github.com/GenSpectrum/loculus-config) where we have configured this. + +## Without Docker + +You can compile and run Loculus from source code if you do not want to use Docker. We do not have a dedicated guide for this at the moment and recommend reading the [Docker Compose example](#with-docker-compose) to understand how the sub-services should be connected and the (developer) documentation of the individual services for getting them running: + +- [Loculus backend](https://github.com/loculus-project/loculus/tree/main/backend) +- [Loculus website](https://github.com/loculus-project/loculus/tree/main/website) +- [PostgreSQL](https://www.postgresql.org/docs/) +- [Keycloak](https://www.keycloak.org/guides) +- [SILO](https://github.com/GenSpectrum/LAPIS-SILO) +- [LAPIS](https://github.com/GenSpectrum/LAPIS) +- Use the [Nextclade preprocessing pipeline](https://github.com/loculus-project/loculus/tree/main/preprocessing/nextclade) or follow the [preprocessing pipeline specifications](https://github.com/loculus-project/loculus/blob/main/preprocessing/specification.md) to build your own custom pipeline + +Please let us know if you are interested in using Loculus without Docker or Kubernetes! Your feedback will motivate us to create a guide. You are of course also very welcome to contribute to the documentation if you have successfully deployed a Loculus instance and have written down the steps. diff --git a/docs/src/content/docs/guides/getting-started.md b/docs/src/content/docs/for-administrators/setup-with-kubernetes.md similarity index 99% rename from docs/src/content/docs/guides/getting-started.md rename to docs/src/content/docs/for-administrators/setup-with-kubernetes.md index de82f479d9..382a8e85ad 100644 --- a/docs/src/content/docs/guides/getting-started.md +++ b/docs/src/content/docs/for-administrators/setup-with-kubernetes.md @@ -1,6 +1,6 @@ --- -title: Deploying a loculus instance -description: How to deploy a loculus instance +title: Setup with Kubernetes +description: How to deploy a Loculus instance with Kubernetes --- # Prerequisites diff --git a/docs/src/content/docs/guides/user-administration.md b/docs/src/content/docs/for-administrators/user-administration.md similarity index 100% rename from docs/src/content/docs/guides/user-administration.md rename to docs/src/content/docs/for-administrators/user-administration.md diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index c8bc2a3dac..9061b80f6d 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -8,7 +8,7 @@ hero: file: ../../assets/db.webp actions: - text: Getting started with Loculus - link: ./guides/getting-started/ + link: ./for-administrators/getting-started/ icon: right-arrow variant: primary - text: View a demo instance diff --git a/docs/src/content/docs/introduction/current-state-and-roadmap.md b/docs/src/content/docs/introduction/current-state-and-roadmap.md new file mode 100644 index 0000000000..719b5e510c --- /dev/null +++ b/docs/src/content/docs/introduction/current-state-and-roadmap.md @@ -0,0 +1,8 @@ +--- +title: Current state and roadmap +description: The current state and roadmap of Loculus +--- + +The Loculus software is already in a stable state and is being used by production systems (see "Known instances" below). You are welcome to explore this repository and try it out yourself. However, please note that we are planning to revise the configuration files and the APIs before the official 1.0 release. Furthermore, the documentation is currently quite sparse. We plan to release 1.0 with stable APIs and comprehensive documentation by the end of 2024. + +If you are looking for a software to manage sequencing data and would like to know whether Loculus might be a suitable tool for you, please feel free to reach out. We would love to hear about your project and take your needs and requirements into consideration when we plan the further development.