Skip to content

Running locally

The Reservoir Genome Browser can be run locally to view files on your computer without uploading to the hosted instance at resgen.io.

Usage requires a license. If you already have a resgen subscription, you can get a license from resgen.io.

If you don't have a license, you are entitled to run locally and host directories with a maximum of 10 datasets.

Starting locally

Starting locally will start resgen as a server on your local computer. You can access the UI at http://localhost:1807 (The port can be changed using the --port flag in the commands below)

resgen manage start ~/my-directory

If you are on an M* Mac you'll need to add --platform=linux/arm64/v8 for the right Docker image to be used.

resgen manage start ~/my-directory --platform=linux/arm64/v8

Create local user

Even when running locally you need to set up a user:

resgen manage create-user ~/my-directory

Synchronize datasets

Resgen maintains its own database of datasets, you'll need to synchronize manually when anything is added to the directory outside of resgen.

resgen manage sync-datasets ~/my-directory

Getting logs

If an error occurs, you can get the latest logs:

resgen manage logs ~/my-directory [nginx,uwsgi,celery]

The last parameter specifies the service to get logs for. In the majority of cases this will be uwsgi.

Advanced functionality

Creating a superuser

A superuser can use the admin interface to modify users, projects and datasets.

resgen manage create-superuser ~/my-directory

Starting with a non-standard image

One may wish to start resgen with an older image:

resgen manage start --image <image_name> ~/my-directory

Viewing a dataset

Use the resgen manage view command to view local datasets.

The following command will generate a sequence logo plot from the 4th (1-based) column in the given csv file. It will do this by doing a multiple sequence alignment using ClustalO. Be careful with how many sequences are provided and how long they are lest the command take too long too finish.

resgen manage view simulated_sars2_spike_15.csv \
  -t colnum:4 \
  -tt sequence-logo \
  -tp top

The extra options are:

  • -t - Add a tag to the created dataset saying to use column number 4. It's also possible to use -t colname:blah to tell it to use the column name blah
  • -tt - The track type to use (sequence-logo)
  • -tp - Position this track up top. As opposed to on the left or right

Other options

  • -t header:false - Indicate that the CSV file has no header
  • -t colname:<column_name> - Indicate that a named column should be used. This will take precedence over colnum:<column number>

Displaying a pileup plot

The following command will generate a pileup plot from the column named 'sequence' (t colname:sequence) in the csv file. It will align all values in the sequence column against the value in the first row (-t refrow: 1)

resgen manage view simulated_sars2_spike_15.csv \
  -t colname:sequence \
  -t refrow:1 \
  -dt reads \
  -ft pileup-csv \
  --platform linux/amd64

The extra options are:

  • -t colname:sequence - Use the values in the sequence column of the csv file
  • -t refrow:1 - Use the first row as the reference to align reads against
  • -dt reads - Indicate that these are to be treated as "reads" to be displayed in a pileup track
  • -ft:pileup-csv - Treat the file as containing pileup data
  • --platform linux/amd64 - Use the linux/amd64 architecture for the resgen docker image