Getting started

Although Sparrow is a complex software application, it is packaged in a set of Docker containers, enabling relatively seamless cross-platform installation, independent of the configuration of the base system. Local installation is possible, but less supported.

note

Running Sparrow on Windows is somewhat more complex than for Unix (e.g. Linux, Mac) systems. If you want to do this, please see the Sparrow on Windows documentation.

Installing Docker

In its containerized form, Sparrow can be installed easily on any Unix environment. This containerized distribution strategy will allow easy deployment on any infrastructure (local, cloud hosting, AWS/Azure, etc.). The Docker toolchain is stable and open-source.

The only installation requirements on Unix host systems (e.g. Linux and MacOS) are docker and python3. First, install Docker and docker-compose using the instructions for your platform, and make sure your user can run docker without root permissions (typically sudo usermod -aG docker ${USER}). Installation is also possible on Windows 10 using Windows Subsystem for Linux.

Getting the code

Currently, all installations of Sparrow require you to fetch the source code from GitHub. Work is progressing on a "standalone" version of Sparrow that does not require interacting with the source code. But for now, only development installation is supported.

git clone https://github.com/EarthCubeGeochron/Sparrow.git
cd Sparrow

Installing the command-line interface

Sparrow is administered using the sparrow command-line interface. This command wraps application management, database management, and container-orchestration subcommands (wrapping Docker compose) in a single executable, simplifying basic management tasks. Lab-specific subcommands (e.g. for import scripts) can be included in this interface.

To install the command-line application, run the setup command within the Sparrow repository directory (you will be asked for a password).

make install

This will build a development version of the sparrow command-line runner.

note

make install requests sudo privilege elevation so that it can install sparrow to /usr/local/bin, which allows the command to be run without a path prefix on most systems. If you want to install to a different location, you can instead run SPARROW_INSTALL_DIR=<root-path> make install. This will install sparrow to <root-path>/bin/sparrow.

Running Sparrow

Typing sparrow at the command line will download and build containers (this will take a long time on initial run) and show the application's help page. Seeing the help page successfully means the application has been installed.

The Sparrow application can be run using the command sparrow up. The environment variable SPARROW_SECRET_KEY must be set before running, but other variables will be set to default values if not provided. Thus, a minimal working Sparrow demo can be run using the following command:

SPARROW_SECRET_KEY=TemporaryKey sparrow up

This command will spin up a database engine, frontend, backend, and gateway service (details of each service can be found in docker-compose.yaml) and automatically run the sparrow init command to set up database tables. The Sparrow web interface can then be accessed at http://localhost:5002; the API can be found at http://localhost:5002/api.

Creating a user

On navigating to the web interface for the first time, you will not be logged in — indeed, no user will exist! To create a user, run the sparrow create-user command and follow the prompts. There should be a single row in the user table after running this command. Note: the SPARROW_SECRET_KEY environment variable is used to encrypt passwords, so make sure this value is kept consistent through the lifetime of the application.

Running a configured application

Sparrow is configured using a shell script that exports environment variables to customize the Sparrow installation. An example of this script is shown in sparrow-config.sh.example. While not required (environment variables can be set externally), this approach is strongly preferred.

At runtime, the sparrow application finds a configuration file by searching upwards from the current directory until the first file named sparrow-config.sh is found. Alternatively, the location of the configuration file can be set using the SPARROW_CONFIG environment variable. This will allow the sparrow command to be run from anywhere on the system.

The best way to get a basic configured application to test is by running the sparrow create-test-lab <your-directory> command, which will give you a basic lab with a few plugins and a small test dataset, based on the configuration in this directory.

Managing lab implementations of Sparrow as Git repositories is a good idea, as it allows plugins and site content to be versioned and pinned (using Git submodules) to a specific version of Sparrow. This has the added benefit of allowing configurations and lab-specific code to be publicly available to guide future implementations. This approach is taken by the UW Cosmogenic Nuclide lab, Arizona Laserchron Center, WiscAr, the Desert Research Institute, and other implementing facilities.

Inspecting the running application

Several sparrow subcommands allow inspection of the running Sparrow application:

  • sparrow test runs the application's testing suite.
  • sparrow psql allows interaction with the Sparrow database using the standard psql management tool that ships with PostgreSQL.
  • sparrow db-tunnel exposes the PostgreSQL database engine on localhost port 54321 (database sparrow, user postgres). This is useful for schema introspection and data management using GUI tools such as Postico.
  • sparrow shell runs an iPython shell within the application.
  • sparrow shell <container> creates a command-line shell within a Docker container in the application.
  • sparrow config prints the API server configuration.
  • sparrow compose config prints the docker-compose configuration in use for running the containerized application.

Appendix