Install and Setup ReadStore (Tutorial Part 1) - EVOBYTE Digital Biology Data Platforms and Bioinformatics

Quick Guide to Installing and Setting Up ReadStore Basic

If you’re managing Next-Generation Sequencing (NGS) datasets, you know the importance of having a robust system to store, organize, and access your data efficiently. ReadStore Basic is a straightforward solution designed to help researchers and labs manage NGS datasets. This post will guide you through setting up ReadStore Basic on a Linux environment and connecting it to its WebApp interface in just a few steps.

1. Get Your Free 30-Day Trial License

Before starting, obtain a license key from the ReadStore website. There is a free 30 -Day Trial license for you to test purposes. This license gives you access to all features without any commitment. Once you receive your license key and an initial login for the admin account, you’re ready to begin.

2. Installing and Running the ReadStore Basic Server

The ReadStore server stores and manages your NGS datasets, and the web application lets you access the data from your browser.

Requirements

Make sure you have Python 3.10 or higher installed.

Step-by-Step Installation

1. Create a Virtual Environment To isolate ReadStore and manage dependencies easily, create a virtual environment (you can also use Conda if preferred). This step is not mandatory but generally a good idea.

python3 -m venv venv
source venv/bin/activate

2. Install ReadStore Basic Server: Use pip to install the server:

pip3 install readstore-basic

3. Validate Installation: Ensure the installation was successful:

readstore-server -v

4. Start the Server: Define the required directories for your database, backups, and logs, then start the server.

mkdir /path/to/database_dir /path/to/backup_dir /path/to/logs_dir

readstore-server --db-directory /path/to/database_dir --db-backup-directory /path/to/backup_dir --log-directory /path/to/logs_dir

To keep the server running in the background, you can configure it as a Linux systemd service. Check the official README for details.

3. Accessing the ReadStore WebApp

With the server running, access the web app from your browser by navigating to 127.0.0.1:8501. This address works for local setups; however, if you’re running ReadStore on a remote server, you’ll need to set up an SSH tunnel.

Connecting Remotely via SSH Tunnel

On Linux, you can create an SSH tunnel using:

ssh -i path/to/sshkey.pem -L 8501:127.0.0.1:8501 username@host

If you’re on Windows, use PuTTY to set up the SSH tunnel. Follow this PuTTY tutorial to configure your connection.

4. Activating Your License and Setting Up Admin Access

Log in with the initial admin password provided with the activation email and default admin account name. You’ll need to perform a few setup tasks initially:

Change the Admin Password: Move to the Settings page and update the default password for better security.
Enter License Key: In the Settings page, enter the key to activate the application.
Create New Users: Move to the Admin page, create user accounts and grant staging permissions to enable FASTQ file uploads.

Once your user accounts are set up, login and move to the Settings page. Here you can get your user token which you need to configure the ReadStore command line interface (CLI).

5. Setting Up the ReadStore CLI

The CLI simplifies interactions with the server, including uploading files. Here’s how to set it up.

1. Install the CLI

pip install readstore-cli

2. Validate Installation

readstore -v

3. Configure CLI Credentials

readstore configure

Enter your username, token, and select a default output format for queries. The output format defines how queries are returned, and can be set according to your downstream applications.

6. Uploading Your First FASTQ Files

Once your CLI is configured, uploading files is straightforward. Navigate to the folder containing your FASTQ files and run:

readstore upload *.fastq

Log into the ReadStore WebApp, navigate to the Staging page, and confirm your files have uploaded successfully.

Congratulations on Setting Up ReadStore!

In just a few steps, you’ve set up a powerful tool to manage your NGS datasets. With the ReadStore Basic server running, you can securely upload, manage, and access your data, all from an intuitive web interface. Happy sequencing!