Developer Installation

For simple user installation, we suggest using Docker. The instructions below are for those who want to modify DVID code. If installing on Ubuntu, please test this [quick install script](Ubuntu Quick Script).

One-time Setup

DVID uses the buildem system to automatically download and build the specified storage engine (e.g., leveldb), Go language support, and all required Go packages.

Make sure you have the basic requirements:

• Go compiler. We recommend Go 1.5.
• CMake
• git, version >= 1.8 is recommended (git 1.7 is known to have issues fetching some buildem and Go packages).
• mercurial

Both git and mercurial are used by the Go toolchain to download packages.

Before downloading DVID, setup the proper directory structure that adheres to Go standards and clone the dvid repo:

# This is unnecessary if you are already using Go.
# Make sure GOROOT is unset since we are building Go from source.
% mkdir $HOME/go
% export GOPATH=$HOME/go

# Now we download the DVID repo into that Go workspace
% export DVIDSRC=$GOPATH/src/github.com/janelia-flyem/dvid
% mkdir -p $DVIDSRC
% cd $DVIDSRC
% git clone https://github.com/janelia-flyem/dvid .

You should also have a BUILDEM_DIR, either an empty directory or your previous buildem directory where you'll compile all the required software and eventually place the compiled dvid executable. You'll want to set your environment variables like so:

% export BUILDEM_DIR=/path/to/buildem/dir
% export PATH=$BUILDEM_DIR/bin:$PATH

For Linux, export your library path:

% export LD_LIBRARY_PATH=$BUILDEM_DIR/lib:$LD_LIBRARY_PATH

For Mac, the library path is specified as DYLD_LIBRARY_PATH:

% export DYLD_LIBRARY_PATH=$BUILDEM_DIR/lib:$DYLD_LIBRARY_PATH

In the above, we are saying to use the executables created in the $BUILDEM_DIR/bin directory first, which should include the DVID executable, and also use buildem-created libraries.

Create an empty build directory used to build just dvid:

% cd $DVIDSRC
% mkdir build
% cd build
% cmake -D BUILDEM_DIR=$BUILDEM_DIR ..

The example above creates a build directory in the dvid repo directory, which also has a .gitignore that ignores all "build" and "build-*" files/directories.

If you haven't built with that buildem directory before, do the additional steps:

% make
% cmake -D BUILDEM_DIR=$BUILDEM_DIR ..

You can specify a particular storage engine for DVID by adding a -D DVID_BACKEND=... option to the above cmake command. It currently defaults to basholeveldb (the Basho-tuned leveldb). Here's an example of configuring two storage backends for compilation, a basholeveldb "mutable" store and a Janelia-specific kvautobus "immutable" store:

% cmake -D DVID_BACKEND="basholeveldb;kvautobus" -D BUILDEM_DIR=$BUILDEM_DIR ..

Making and testing DVID

Make dvid:

% make dvid

This will install a DVID executable 'dvid' in the buildem bin directory.

Tests can be run by the following:

% make test

Server tuning for big data (optional but recommended)

Particularly when using leveldb variants, we recommend modifying default "max open files" and also avoiding extra disk head seeks by turning off noatime, which records the last accessed time for all files. See this explanation on the basho page

First, make sure you allow a sufficient number of open files. This can be checked via the "ulimit -n" command in Linux and Mac. We suggest raising this to 65535 on Linux and at least 8192 on a Mac. You might have to modify the (1024 has proven sufficient for Teravoxel repos on 64-bit Linux using standard leveldb but this had to be raised to several thousand even for 50 Gigavoxel repos on Mac.)

% ulimit -n 65535

You can also set max file open limits for a dvid-specific user by editing appropriate sys files.

Second, disable access-time updates for the mount with your DVID data. In Linux, you can add the noatime mounting option to /etc/fstab for the partition holding your data. The line for the mount holding your DVID data should like something like this:

/dev/mapper/vg0-lv_data    /dvid/data     xfs      noatime,nobarrier     1 2

Then remount the disk:

% mount /dvid/data -o remount

Memory profiling

DVID uses an integrated memory profiling system. To start memory profiling, visit http://path-to-dvid-server/profiler/start. You can then visit http://path-to-dvid-server/profiler/info.html to view the real-time graph of memory usage. Stop profiling by visiting http://path-to-dvid-server/profiler/stop.