Getting started with Sparrow

Sparrow is a complex software application, but it has been packaged for easy setup on a wide variety of systems, from personal laptops to servers (both physical and in the cloud). This guide focuses on setting up the system on personal and workspace computers (i.e., those with and a graphical environment and attached screens). However, some aspects of server installation are touched on.

Install Docker

The first step to running Sparrow is to install the Docker application using the instructions for your platform.

Sparrow is packaged in a set of Docker containers. A container is a miniature virtual machine designed to hold a single application and all of its dependencies. Docker enables relatively seamless cross-platform installation of Sparrow, independent of the configuration of the base system. The Docker toolchain is stable, open-source, and supported by helpful tools like Docker Desktop for running applications in development. Local installation (i.e., without Docker) is straightforward but unsupported at the moment.

Once you have installed Docker, you should be able to access it at the terminal using the docker command. Running a basic example container (e.g., docker run hello-world) is a good idea to make sure that everything is set up properly.

For server installations, it is a good idea to ensure that your user can run docker without root permissions, by running sudo usermod -aG docker ${USER} or your distribution's equivalent. This is automatically set up when using Docker Desktop.

Install the sparrow executable

Sparrow's stack of Docker containers are wrapped in a command-line interface that simplifies management of the system. Sparrow's command line application is a small Python package that has been bundled with PyInstaller. New versions of Sparrow are released periodically on Github

The sparrow CLI is most easily installed using a convenience script that installs it in the right location based on common configurations. This can be downloaded and run using the following terminal snippet:

bash -c "$(curl -fsSL https://sparrow-data.org/get-sparrow.sh)"

This command will download Sparrow to your /usr/local/bin and /usr/local/opt (or ~/.sparrow/opt on MacOS) directories . In your favorite terminal or shell, run the command from above. If it is installed properly you should see the output Sparrow executable installed!

Once you have installed the sparrow CLI, you can try running it in your terminal.

sparrow

The first time it is run, the Sparrow CLI builds Docker containers and sets some basic configuration. Several errors commonly arise at this step:

• command not found: Sparrow might not be properly referenced on your command search PATH.
• Cannot connect to the Docker daemon or similar: You may not have started the Docker engine.
• The Docker containers might not build properly, for a variety of reasons. If this is the case, follow the [Troubleshooting guide][troubleshooting].

If the Sparrow command-line interface has been installed correctly, it will print some build output, followed by a list of possible Sparrow commands.

Set up a Sparrow database and server

An unconfigured instance of Sparrow can be started 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 several Docker containers including a database engine, frontend, backend, and gateway service and automatically run the sparrow init command to set up initial database tables. The Sparrow web interface can then be accessed at http://localhost:5002; the API can be found at http://localhost:5002/api.

Run a configured application

In practice, Sparrow needs to be configured differently for each lab that runs the software. Typically, this is done by creating a lab configuration directory with a sparrow-config.sh file in it. 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 fsearches upwards from the current directory until the first file named sparrow-config.sh is found. This behavior is similar to that of the git command.

The quickest way to set up an instance of Sparrow is by running

sparrow create-test-lab <your-directory>

This will create a pre-configured Sparrow instance with a basic configuration file (sparrow-config.sh), a few plugins, and a small test dataset.

Create 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.

Version your lab configuration

Most labs implementing Sparrow manager their configuration and plugins as Git repositories, allowing lab-specific code to be developed and improved over time. This also allows lab instances to be made publicly available to guide future implementations.

Several reference implemetations are available:

• University of Wisconsin Cosmogenic Nuclide lab
• Arizona Laserchron Center
• WiscAr
• WiscSIMS
• the Desert Research Institute Luminescence Lab (OSL)
• the Boise State isotope geochemistry lab
• CU Trail (thermochronology)

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

• Local development
• Core extensions