Repository files navigation

STOQS is a geospatial database and web application designed to give oceanographersefficient integrated access toin situ measurement andex situ sample data.Seehttp://www.stoqs.org.

First, installVagrant and andVirtualBox— there are standard installers for Mac, Windows, and Linux. (You will also needX Windows System sofware on your computer.) Then create an empty folder off yourhome directory such asVagrants/stoqsvm, open a command prompt window, cd to that folder, and enter thesecommands:

curl"https://raw.githubusercontent.com/stoqs/stoqs/master/Vagrantfile" -o Vagrantfilecurl"https://raw.githubusercontent.com/stoqs/stoqs/master/provision.sh" -o provision.shvagrant plugin install vagrant-vbguestvagrant up --provider virtualbox

The Vagrantfile and provision.sh will provision a development system with an NFS mounteddirectory from your host operating system. If your host doesn't support serving files viaNFS (most Windows hosts don't support NFS file serving) then you'll need to edit these filesbefore executingvagrant up. Look for thesupport NFS file serving comments in thesefiles for the lines you need to change.

Thevagrant up command takes an hour or so to provision and setup a complete CentOS 7STOQS Virtual Machine that also includes MB-System, InstantReality, and all the Python data sciencetools bundled in packages such as Anaconda. You will be prompted for your admin passwordfor configuring a shared folder from the VM (unless you've disabled the NFS mount). All connections to this VM areperformed from the the directory you installed it in; you must cd to it (e.g.cd ~/Vagrants/stoqsvm) before logging in with thevagrant ssh -- -X command. Afterinstallation finishes log into your new VM and test it:

vagrant ssh -- -X# Wait for [vagrant@localhost ~]$ promptexport STOQS_HOME=/vagrant/dev/stoqsgit# Use STOQS_HOME=/home/vagrant/dev/stoqsgit if not using NFS mountcd$STOQS_HOME&&source venv-stoqs/bin/activateexport DATABASE_URL=postgis://stoqsadm:CHANGEME@127.0.0.1:5438/stoqs./test.sh CHANGEME load noextraload

In another terminal window start the development server (after acd ~/Vagrants/stoqsvm):

vagrant ssh -- -X# Wait for [vagrant@localhost ~]$ promptexport STOQS_HOME=/vagrant/dev/stoqsgit# Use STOQS_HOME=/home/vagrant/dev/stoqsgit if not using NFS mountcd$STOQS_HOME&&source venv-stoqs/bin/activateexport DATABASE_URL=postgis://stoqsadm:CHANGEME@127.0.0.1:5438/stoqsstoqs/manage.py runserver 0.0.0.0:8000 --settings=config.settings.local

Visit your server's STOQS User Interface using your host computer's browser:

http://localhost:8008

More instructions are in the doc/instructions directory — seeLOADINGfor specifics on loading your own data. For example, you may create your own database of an archived MBARI campaign:

cd stoqsln -s mbari_campaigns.py campaigns.pyloaders/load.py --db stoqs_cce2015

You are encouraged to contribute to the STOQS project! Please seeCONTRIBUTINGfor how to share your work. Also, see exampleJupyter Notebooksthat demonstrate specific analyses and visualizations that go beyond the capabilities of the STOQS User Interface.Visit theSTOQS Wiki pages for updates and links to presentations.Thestoqs-discuss list in Google Groups is alsoa good place to ask questions and engage in discussion with the STOQS user and developer communities.

Supported by the David and Lucile Packard Foundation, STOQS undergoes continual developmentto help support the mission of the Monterey Bay Aquarium Research Institue. If you have yourown server you will occasionally want to get new features with:

git pull

First, installDocker anddocker-composeon your system. Then clone the repository; in the docker directory copy thetemplate.env file to.envand edit it for your specific installation, then executedocker-compose up:

git clone https://github.com/stoqs/stoqs.git stoqsgitcd stoqsgit/dockercp template.env .envchmod 600 .env# You must then edit .env and change settings for your environmentdocker-compose up

If the directory set to the STOQS_VOLS_DIR variable in your .env file doesn't exist then theexecution ofdocker-compose up will create the postgresql database cluster, load a defaultstoqs database, and execute the unit and functional tests of the stoqs application. If youdon't see these tests being executed (they will take several minutes) then check for errormessages.

Once you see... [emperor] vassal /etc/uwsgi/django-uwsgi.ini is ready to accept requestsyou can visit the site athttps://localhost — it uses a self-signed certificate, so yourbrowser will complain and you will need to add an exception. (The nginx service also deliversthe same app athttp://localhost:8000 without the certificate issue.)

The default settings intemplate.env will run a production nginx/uwsgi/stoqs server configuredforhttps://localhost in a Vagrant virtual machine. To configure a server for intranet or public serving ofyour data follow the instructions provided in the comments for the settings in your.env file.After editing your.env file you will need to rebuild the images and restart the Dockerservices, this time with the-d option to run the containers in the background:

docker-compose builddocker-compose up -d

The above commands should also be done following agit pull in order to deploy updatedsoftware on your server.

One thing that's good to do is monitor logs and check for error messages, this can be done with:

docker-compose logs -f

You can execute Python code in the stoqs server from your host by prefacing it withdocker-compose exec stoqs(Usedocker-compose run stoqs to launch another container for long-running processes), forexample to load some existing MBARI campaign data:

docker-compose run stoqs stoqs/loaders/load.py --db stoqs_simz_aug2013

(To load MBARI Campaigns you will need to have uncommented theCAMPAIGNS_MODULE=stoqs/mbari_campaigns.pyline in your .env file. Make sure that you do not have a symbolic link namedcampaigns.py in the stoqsdirectory. This is needed only for a Vagrant development machine — it's best to keep the directory usedfor a Docker deployment separate from one used for Vagrant.)

In another window monitor its output:

docker-compose run stoqs tail -f /srv/stoqs/loaders/MolecularEcology/loadSIMZ_aug2013.out# Or (The stoqs code is bound as a volume in the container from the GitHub cloned location)tail -f stoqsgit/stoqs/loaders/MolecularEcology/loadSIMZ_aug2013.out

You may also usepg_restore to more quickly load an existing Campaign database on your system.For instructions click on the Campaign name in the top bar of a Campaign on another STOQS server,for example onMBARI's Public STOQS Server.

If you use STOQS for your research please cite this publication:

McCann, M.; Schramm, R.; Cline, D.; Michisaki, R.; Harvey, J.; Ryan, J., "Using STOQS (The spatialtemporal oceanographic query system) to manage, visualize, and understand AUV, glider, and mooring data,"inAutonomous Underwater Vehicles (AUV), 2014 IEEE/OES, pp.1-10, 6-9 Oct. 2014doi: 10.1109/AUV.2014.7054414