m3-quickstart

A simple and easy method to run MBARI's Video Annotation and Reference System.

News

February 8, 2024

We are currently doing some major updates to the backend services, annosaurus and vampire-squid.

f you're currently using m3-quickstart to run a VARS system, run git pull. Beyond that, there's no need for you to do anything at the moment. I've pinned the correct versions of the services for you to continue running VARS uninterrupted on your systems.

Going forward, I will provide migration scripts to update PostgreSQL and SQL Server databases to work with the updated services, providing a migration path for users.

If you are planning to set up a new VARS system in the near future, I would advise you to wait until about the end of February 2024. At that point, I will have updated this project to work with the new services, and you can run with the latest and greatest changes.

Prerequisites

• Docker - Required to launch the VARS microservices
• Python >= 3.7 - Runs the supporting scripts. The additional python requirements are in bin/etc/python/requirements.txt
• ffmpeg - Required to use the pyhon video registration scripts
• Java 17+ - Builds the VARS Query and VARS Knowledgebase applications.
• scala-cli - Runs some of the supporting scripts.
• VARS Annotation v1.5.3 or earlier - The annotation application
• A VARS Friendly-video player. It can be anyone of the following:
  • Sharktopoda - macOS-only
  • jsharktopoda - cross-platform
  • Cthulhu - macOS (amd64, not support on arm64) and Linux. This video player allows users to draw bounding boxes directly on video. Requires that VLC is installed too.

tl;dr

Build everyting

To get M3/VARS built and running on your own server. Do the following in a terminal:

# Get setup
git clone git@github.com:mbari-media-management/m3-quickstart.git
cd m3-quickstart

# Start the web server, database, and VARS services
# The first time it's run it takes a while. Be patient.
bin/docker_start.sh

# Builds some custom VARS apps under temp/apps
# You need GITHUB_TOKEN and GITHUB_USERNAME environment variables set.
#   see https://github.com/mbari-org/maven#gradle
export GITHUB_TOKEN=<your github token>
export GITHUB_USERNAME=<your github username>
bin/vars_build.sh

# Next steps needed to run python support scripts
pip install -r bin/etc/python/requirements.txt

Next Steps

1. Open a browser to http://localhost to verify that things are working.
2. Run the VARS Knowledgebase application. The first time it's run it will ask you to create an admin account. It will be located in m3-quickstart/temp/apps. Remember your admin password!!
3. Register your first video with VARS. You can use any video with a URL or you can put them in m3-quickstart/temp/media and browse to it (e.g. http://localhost). Once you have a URL use bin/vars_register_media.sh to register it in the VARS Video Asset Manager.
4. Download VARS Annotation and configure it as described here.

Any computer on you network can connect to the VARS services you're running. You can annotate from other machines on your network.

Clean up

If you want to shutdown the M3/VARS software stack, run m3-quickstart/bin/docker_stop.sh.

Details

Registering a video

Before a video can be annotated, VARS needs to know about it. The first step is to make your video web accessible. If you've already run docker_start.sh, you have a web server running that is capable of serving video. You can put the video in m3-quickstart/temp/media and browse to it under http://localhost/media.

The next step is to register the video. It's highly recommended that you follow a naming convention described here. To help you get started, there's a script <bin/vars_register_media.sh> you can use to register a video with VARS. It's usage is:

cd m3-quickstart
bin/vars_register_media.sh <camera id> <deployment id> <video url>

• camera-id - An identifier for the camera or platform that collected the video
• deployment id - An identifier for the deployment of the camera
• video url - The URL to your video. Don't use localhost!! You can browse to your machine using it's network name instead.

# Example
bin/vars_register_media.sh "Doc Ricketts" "Doc Ricketts 2309" "http://m3.shore.mbari.org/videos/master/2021/11/2309/D2309_20211109T132100.3Z_prores.mov"

VARS Annotation

VARS Annotation will run on Window, macOS, and Linux. At MBARI, we use macOS. If you need a build of VARS Annotation for your operating system submit create a request here