Server Installation - ngageoint/voxel-globe GitHub Wiki

TL;DR

  1. Install Docker, git, and git-lfs (and Nvidia drivers and nvidia-docker in Linux)
  2. git clone --recursive https://github.com/ngageoint/voxel-globe.git
  3. cd voxel_globe
  4. ./just install
  5. ./just start

You should only ever run ./just install once. See here for instructions on how to upgrade to the latest version of VoxelGlobe.

Supported Operating Systems

Linux, Windows, and Mac are supported for running the VoxelGlobe Server. Many of the algorithms require GPU support, and currently GPU is only supported in Linux. Windows GPU support will probably never be added due to numerous issues (such as celery, and GPU Passthrough limitations). Unless technology changes, Windows and Mac will not support GPU use. When VoxelGlobe runs in Windows/Mac, it will default to CPU when possible, and fail when it needs CUDA.

Requirements

Linux (Recommended)

  1. Nvidia Drivers

    1. Mint - If your graphics card is from Nvidia, perform the following steps to install the Nvidia drivers:

      1. Open the Driver Manager
      2. Choose the Nvidia drivers and wait for them to be installed
      3. Reboot the computer

    2. Other - You generally have a number of ways you can install Nvidia drivers in Linux

      1. Install the CUDA repo and use your package manager to install cuda
        1. Go here
        2. Select Linux, x86_64, your Operating System or closest equivalent, OS Version, then download the rpm(network) file (local options will work too, but not covered here)
        3. sudo yum install cuda-repo-rhel7-8.0.44-1.x86_64.rpm
        4. Install the EPEL Repo
        5. sudo yum install cuda
      2. Alternative method: Install the Nvidia driver for your card from the Nvidia site

        1. Start be by searching Nvidia

        2. For example, if you have a GTX 880M, choose

          • Product Type: GeForce
          • Product Series: GeForce 800M Series (Notebook)
          • Product: GeForce GTX 880M
          • Operating System: Linux 64-bit
          • Language: English (US)

        3. Click "Search"

        4. The most recent version of the driver will show up (you have to go here to pick an arbitrary version of the driver)

        5. Download the driver, for example, this is version 367.57

        6. Open up a terminal, and cd into the directory where your downloaded the file. Often, this is your "Download" folder, so

           cd ~/Downloads

        7. Run the installer. For version 367.57, this looks like

           bash ./NVIDIA-Linux-x86_64-367.57.run

        8. Follow the onscreen instructions, and the drivers should install

      3. Alternative method: Install the CUDA repo and use your package manager to install just the nvidia driver (untested)
        1. Same as above, but instead of sudo yum install cuda try yum install nvidia-kmod.x86_64 xorg-x11-drv-nvidia.x86_64 xorg-x11-drv-nvidia-gl.x86_64 xorg-x11-drv-nvidia-libs.x86_64
      4. Ubuntu (Not tested)

    3. Reboot your computer once the drivers are installed, this will allow them to be loaded and start working. Once rebooted, run nvidia-smi to verify the drivers are working. For example:

       Tue Nov  1 16:21:15 2016       
 +------------------------------------------------------+                       
 | NVIDIA-SMI 361.42     Driver Version: 361.42         |                       
 |-------------------------------+----------------------+----------------------+
 | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
 | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
 |===============================+======================+======================|
 |   0  GeForce GTX 680     Off  | 0000:01:00.0     N/A |                  N/A |
 | 34%   53C    P8    N/A /  N/A |    380MiB /  4095MiB |     N/A      Default |
 +-------------------------------+----------------------+----------------------+
 |   1  GeForce GTX 580     Off  | 0000:02:00.0     N/A |                  N/A |
 | 44%   52C   P12    N/A /  N/A |      8MiB /  3071MiB |     N/A      Default |
 +-------------------------------+----------------------+----------------------+
 |   2  Tesla K20c          Off  | 0000:03:00.0     Off |                  Off |
 | 30%   36C    P8    16W / 225W |     14MiB /  5119MiB |      0%      Default |
 +-------------------------------+----------------------+----------------------+
                                                                    
 +-----------------------------------------------------------------------------+
 | Processes:                                                       GPU Memory |
 |  GPU       PID  Type  Process name                               Usage      |
 |=============================================================================|
 |    0                  Not Supported                                         |
 |    1                  Not Supported                                         |
 +-----------------------------------------------------------------------------+

  2. Docker - Install using Docker's instructions

    • Make sure your username has docker group permissions by running id {username}. You should see groups= followed by a number of groups, one of which says 999(docker) (where the number may be different) in the output. If you do NOT see docker, see here and try id {username} again. Once you are logged out and log in again, hello-world should work now.

    • Do not forget to run set docker to start on boot. The instructions for your UsuaOS have a "Start the docker daemon at boot" or "Starting Docker" section. Older versions of Ubuntu may be more tedious.

    • To hello-world test, run docker run -it --rm hellow-world and you should see:

        Hello from Docker!
  This message shows that your installation appears to be working correctly.

  To generate this message, Docker took the following steps:
   1. The Docker client contacted the Docker daemon.
   2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
   3. The Docker daemon created a new container from that image which runs the
      executable that produces the output you are currently reading.
   4. The Docker daemon streamed that output to the Docker client, which sent it
      to your terminal.

  To try something more ambitious, you can run an Ubuntu container with:
   $ docker run -it ubuntu bash

  Share images, automate workflows, and more with a free Docker Hub account:
   https://hub.docker.com

  For more examples and ideas, visit:
   https://docs.docker.com/engine/userguide/

  3. Git

  4. Nvidia-Docker

    • Make sure Docker is installed and running before attempting this, and that the nvidia drivers are loaded by testing them as mentioned above.
    • On Fedora/RHEL/CentOS, run systemctl enable nvidia-docker to enable nvidia-docker on boot

  5. Git-LFS

    1. Install git-lfs

      • For Debian operating systems (Ubuntu, Mint, etc...) run

          curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
  apt-get install git-lfs

      • For Fedora operating systems (RHEL, CentOS, etc...) run

          curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.rpm.sh | sudo bash
  yum install git-lfs

      • If for any reason this does not work, you do not have root, or you are using another operating system, just go here and download the latest Linux AMD64 package. Untar the git-lfs executable and put it in your path (or run install.sh if you do have root).

    2. Run sudo git lfs install once, or git lfs install for every non-root user you want git checkout to work for (probably just your user account).

Mac

  1. Docker
  2. Git
  3. Git-LFS
    1. Install git-lfs
      • Click download, and untar the file and run install.sh
      • Or You can use brew install git-lfs
      • If for any reason this does not work, or you do not have permission, just go here and download the latest Mac AMD64 package. Untar the git-lfs executable and put it in your path (or run install.sh if you do have permissions).
    2. Run sudo git lfs install once, or git lfs install for every non-root user you want git checkout to work for (probably just your user account).

Windows

  1. Docker
  2. Git
  3. Git-LFS
    1. Install git-lfs
      • Go here and click download, and run the installer
      • If for any reason this does not work, you do not have root, or you are using another operating system, just go here and download the latest Windows AMD64 package. Unzip the git-lfs executable and put it in your path.
    2. As administrator, run git lfs install --system once, or git lfs install for every user you want git checkout to work for (probably just your user account).

Installation

Cloning

  • The easiest way to clone is to

      git clone --recursive https://github.com/ngageoint/voxel-globe.git

  • The quickest way to clone is to

      GIT_LFS_SKIP_SMUDGE=1 git clone --recursive https://github.com/ngageoint/voxel-globe.git
  cd voxel_globe
  git lfs pull

  • If you prefer to use ssh checkout (on github and bitbucket), you can switch the submodules over to ssh

      git clone [email protected]:ngageoint/voxel-globe.git
  cd voxel_globe
  ./just ssh-submodules
  git submodule init
  git submodule update

Setup

Once you are in the voxel_globe repo dir, simply run

./just install

Starting

./just start