nextstrain quickstart guide - several issues and need of updates

[davidcroll]

Hi,

I'm David and quite new to the team. As a first task, @rneher directed me to review the Quickstart guide which is a bit outdated.

I'm checking whether this Quickstart guide is working, and which problems are cropping up. Expect this issue to evolve over the next days, as I'm re-testing a few things.

But... anyway: Feel free to make comments or propose solutions.

Testing environment

I'm using Xubuntu 20.10 in VirtualBox. The installation is unchanged, save for the fish console (which I love) and augur from the Ubuntu repository. augur from the repo is a problem, as it is quite old. I will be re-testing the whole affair with the more recent augur installed through python3-pip and from source (git).

Here, the various issues:

1 - Python version

Revise the guide to mention Python 3.8. Python 3.6 has been released in December 2016. Reminding people to use Python > 3.5 is a bit over-cautious nowadays.

2 - PATH issue after python3-pip install of nextstrain-cli

The guide asks to do python3 -m pip install nextstrain-cli.

When the user - as told to - enters nextstrain version next, then the program isn't found. This was confusing (even to me), and this is a transient error because nextstrain is not installed on PATH.

Solution: Tell the user to log out - and in again.

3 - nextstrain.cli version number

When the quickstart guide mentions version 1.4.1 (instead of 3-ish), then it really shows how much development work has been done!

4 - Docker installation

The guide mentions: On Linux, your package manager should include a Docker package

Well, what am I to do?

I google "install docker on ubuntu", I find a solution, and then...

sudo apt install docker.io
sudo systemctl enable --now docker

## The recommended test...
sudo docker run hello-world

These three lines could be added to the quickstart guide - if they are the right ones.

5 - Checking nextstrain setup

So, we have nextstrain check-setup. In contrast to the old guide, nowadays a lot of other conditions are being tested. In my case, I got this result:

vm@vm ~> nextstrain check-setup
nextstrain-cli is up to date!
 
Testing your setup…
docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/create: dial unix /var/run/docker.sock: connect: permission denied.
See 'docker run --help'.
 
## docker is not supported
✔ yes: docker is installed
✘ no: docker run works
? unknown: containers have access to >2 GiB of memory
✔ yes: image is new enough for this CLI version

## native is not supported
✔ yes: snakemake is installed
✔ yes: augur is installed
✘ no: auspice is installed
 
## aws-batch is not supported
✘ no: job description "nextstrain-job" exists
✘ no: job queue "nextstrain-job-queue" exists
✘ no: S3 bucket "nextstrain-jobs" exists
 
No good.  No support for any Nextstrain environment.

So, we have at least four new issues:

5.1 Augur

As I already have installed augur from a repository, it says "augur is installed". But if I didn't, would augur get installed during the python3 -m pip install nextstrain-cli step?

5.2 Auspice is missing

Is auspice contained in a newer version of augur? (Or a newer version of nextstrain?)

5.3 Docker complains about permissions being denied

This could be solved, mayhaps, with a proper installation of Docker. If the (Linux) user is simply told to install Docker from a repository - which I did - he/she might run into troubles.

5.4 Amazon Web Services

It's not clear what AWS is needed for, and the guide, hitherto, didn't mention AWS at all.

[davidcroll]

I've run through the quickstart guide a second time, this time with less difficulties.

pip

• Mention sudo apt install python3-pip, because some users do not have pip installed.

Docker

On Linux, your package manager should include a Docker package.

Nah. This way I ran into the issues described above. The better idea is to follow the instructions here. (And people who run Ubuntu 21.04 (development release) have to add the older Ubuntu package repository.)

The instructions here solved the Docker permissions issue.

conda

One might think python3 -m pip install conda would do the job - but in the end, I only got it running with the installer on [https://conda.io/miniconda.html].

Final note

These instructions seem to be geared towards Linux users who already know how to navigate issues quite well. There are a few detours and solutions need to be gleaned from other instruction and help sites. It could be a lot more straightforward.

Maybe there's a way to simplify the quickstart guide without having to release separate Windows/MacOS/Linux instructions.