Skip to content

Commit

Permalink
Update installation doc
Browse files Browse the repository at this point in the history
- Add a link to the Nextstrain installation guide
- Add table of contents
- Split into "user" and "developer" sections
- Fix Conda environment setup command
- Remove note on bash/env requirement. Don't think it's necessary.
  • Loading branch information
victorlin committed Dec 5, 2022
1 parent fbd661c commit 5c0f03a
Showing 1 changed file with 18 additions and 31 deletions.
49 changes: 18 additions & 31 deletions docs/introduction/install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,67 +2,54 @@
Install Auspice
===============

Prerequisites
=============
.. note::
This is an Auspice-specific installation guide. If you wish to use Nextstrain as a whole, please refer to `the Nextstrain installation guide <https://docs.nextstrain.org/en/latest/install.html>`__.

Auspice is a JavaScript program, and requires `Node.js <https://nodejs.org/>`__ to be installed on your system. Refer to ``engines.node`` in `package.json <https://github.com/nextstrain/auspice/blob/-/package.json>`__ for currently supported versions.
.. contents::
:local:

We highly recommend using `Conda <https://conda.io/docs/>`__ to manage environments, i.e. use Conda to create an environment with Node.js installed where you can use Auspice. It's possible to use other methods, but this documentation presupposes that you have Conda installed.
Install dependencies
====================

To run package scripts, the `bash shell <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`__ and the `env <https://en.wikipedia.org/wiki/Env>`__ command need to be in your ``PATH``. You should already have them on Unix-like systems including Linux and macOS. If you are working from Windows, you can run the installation under Git Bash, MSYS2, or Cygwin. You can also use the Windows Subsystem Linux for a fuller Linux environment.
Auspice is a JavaScript program, and requires `Node.js <https://nodejs.org/>`__ to be installed on your system. Refer to ``engines.node`` in `package.json <https://github.com/nextstrain/auspice/blob/-/package.json>`__ for currently supported versions.

Create a Conda Environment
==========================
We recommend using `Mamba <https://mamba.readthedocs.io/>`__ to create an environment with a specific version of Node.js. It's possible to use other methods, but these are the instructions for Mamba:

.. code:: bash
conda create --name auspice nodejs=14
mamba create -c conda-forge --name auspice nodejs=14
conda activate auspice
..
This parallels `the Nextstrain installation docs <https://nextstrain.org/docs/getting-started/local-installation#install-augur--auspice-with-conda-recommended>`__. You're welcome to use those instead!

Install Auspice from npm
========================
Install Auspice as a user
=========================

.. code:: bash
npm install --global auspice
Auspice should now be available as a command-line program - check by running ``auspice --help``.

If you look at the `release notes <https://docs.nextstrain.org/projects/auspice/en/stable/releases/changelog.html>`__ you can see the changes that have been made to Auspice (see your version of Auspice via ``auspice --version``). To upgrade, you can run

.. code:: bash
npm update --global auspice
Installing from Source
======================
Install Auspice as a developer
==============================

This is useful for debugging, modifying the source code, or using an unpublished feature branch. We're going to assume that you have used Conda to install Node.js as above.
This is useful for debugging, modifying the source code, or using an unpublished feature branch.

.. code:: bash
# activate the correct conda enviornment
conda activate auspice
# grab the GitHub auspice repo
git clone https://github.com/nextstrain/auspice.git
cd auspice
# install dependencies and make `auspice` available globally
npm install --global .
# build auspice (builds the JS client bundle using webpack)
auspice build
# test it works
auspice --version
auspice --help
Updating Auspice should only require pulling the new version from GitHub - it shouldn't require any ``npm`` commands. You will, however, have to re-build Auspice whenever the client-related code has changed, via ``auspice build``.

# Obtain nextstrain.org datasets to view locally (optional)
npm run get-data
Testing if it worked
====================

Updating Auspice should only require pulling the new version from GitHub - it shouldn't require any ``npm`` commands. You will, however, have to re-build Auspice whenever the client-related code has changed, via ``auspice build``.
If installation worked, you should be able to run ``auspice --help``.

0 comments on commit 5c0f03a

Please sign in to comment.