aquarium-local

Running Aquarium Locally

Aquarium is a whole lab automation system integrating inventory, workflow and data management for improved efficiency and reproducibility.

Aquarium is available as a Docker image that can be configured for different deployments. This repository provides a configuration that allows running Aquarium on a single computer such as a laptop, and these instructions are focused on managing a local instance for protocol development. See the Aquarium site for guidance for production deployments.

Running Aquarium with Docker

To run Aquarium in production with Docker on your computer:

Install Docker on your computer.

Get this repository

git clone https://github.com/klavinslab/aquarium-local.git

Change into the aquarium-local directory
```
cd aquarium-local
```
Start Aquarium by running the command
```
chmod u+x aquarium.sh
./aquarium.sh up
```
Note:
- You wont need to change the permissions with chmod each time.
- The first run initializes the database, and so will be slower than subsequent runs. This can take longer than you think is reasonable, but let it finish unmolested.
Once all of the services for Aquarium have started, visit localhost with the Chrome browser to find the Aquarium login page. On WSL (on Windows) the address will be 192.168.99.100 instead of localhost.

When started using the default database, aquarium has a single user with login neptune and password aquarium.

Stopping Aquarium in Docker

To halt the Aquarium services, first type ctrl-c in the terminal to stop the running containers, then remove the containers by running

./aquarium.sh down

Updating/Migrating Aquarium

Running aquarium.sh update will pull updates within a version of Aquarium and migrate the database. However, when a new version of Aquarium is released you will need to run the command

git pull

which will update the configuration files. Run aquarium.sh update to make sure everything is up-to-date, and, finally, restart Aquarium with ./aquarium.sh up as before.

Changing the Database

Aquarium database files are stored in data/db, which allows the database to persist between runs. If this directory is empty, such as the first time Aquarium is run, the database is initialized from the database dump data/mysql_init/dump.sql. The aquarium.sh script will copy data/mysql_init/default.sql to this file, if the dump file does not already exist.

You can use a different database dump by renaming it to this file with

mv data/mysql_init/dump.sql data/mysql_init/dump-backup.sql
mv my_dump.sql data/mysql_init/dump.sql

then removing the contents of the data/db directory

rm -rf data/db/*

and finally restarting Aquarium with ./aquarium.sh up as before. If Aquarium has been updated since the database dump was generated, it is a good idea to run database migrations with aquarium.sh update.

Important: If you swap in a large database dump, the database has to be reinitialized. And the larger the database, the longer the initialization will take. Let the initialization finish.

If you need to change the database frequently, for example while testing code, you can use this script.

When things go wrong

Should you encounter an error, there are a couple of things you can do while Aquarium is still running to collect information that may help us understand what is going on.

share any error output in the terminal where you started Aquarium.

run

./aquarium.sh ps

and let us know what you see.

This command will help us see whether any of the services used by Aquarium have crashed. It should look like this, with all services other than the createbucket service in the Up state.

Name                           Command               State                      Ports
--------------------------------------------------------------------------------------------------------------------
aquarium-local_app_1            /aquarium/entrypoint.sh pr ...   Up       3000/tcp
aquarium-local_createbucket_1   /bin/sh -c  while ! nc -z  ...   Exit 0
aquarium-local_db_1             docker-entrypoint.sh mysqld      Up       3306/tcp, 33060/tcp
aquarium-local_krill_1          /aquarium/entrypoint.sh kr ...   Up       3500/tcp
aquarium-local_s3_1             /usr/bin/docker-entrypoint ...   Up       9000/tcp
aquarium-local_web_1            /docker-entrypoint.sh ngin ...   Up       0.0.0.0:80->80/tcp, 0.0.0.0:9000->9000/tcp

We are looking for any services other than createbucket that have exited.

Note: If you named the directory for the repository something other than aquarium-local that name will appear at the front of the service names.)

run

./aquarium.sh logs > aquarium-error-logs.txt

make an issue and include the information you’ve gathered.

Logs may have information you don’t want public. So be careful if you post this file in a github issue

This site is open source. Improve this page.