For the GAMBIT tutorial we will assume that people interested in following on 
their own laptops have installed GAMBIT using Docker, which removes the need
to compile and wage war with library dependencies. Below we give instructions
on how to install both Docker and GAMBIT. Because of the time and bandwith
needed we highly recommend installing before the session.


IMPORTANT: The complete installation of Docker and the GAMBIT Docker image
will require ~21 GB of available disk space. The total download size is ~4GB.



Install Docker
==============

Mac OSX
-------

Sign up for a Docker account and install "Docker for Mac" here:

  https://docs.docker.com/docker-for-mac/install/

Launch the Docker app (the little whale icon).



Linux
-----

This is a little more work. Install "Docker CE" for your system by following
the instructions here: 

  Ubuntu: https://docs.docker.com/install/linux/docker-ce/ubuntu/
  Debian: https://docs.docker.com/install/linux/docker-ce/debian/
  Fedora: https://docs.docker.com/install/linux/docker-ce/fedora/

The recommended installation option is found under "Install using the repository".
To avoid having to run all Docker commands with "sudo", run these commands once
Docker is installed

  sudo groupadd docker
  sudo usermod -aG docker $USER

and log out and log in again. Info about this can be found here: 

  https://docs.docker.com/install/linux/linux-postinstall/




Download the GAMBIT Docker image:
=================================

Open a terminal and run:

  docker pull gambitbsm/gambit-tutorial

(Go have a coffee…but only a short one…)



Starting the GAMBIT Docker container:
=====================================

Start an interactive session with the GAMBIT container and assign it the name 'gc': 

  docker run -it --name gc gambitbsm/gambit-tutorial

You should now have a shell with GAMBIT plus a lot of backends and utils installed.
You can test that GAMBIT is working by running the following little test scan:

  ./gambit -rf yaml_files/spartan.yaml

This will run a very quick 2D fit using MultiNest. Output files are written to the
directory /work/gambit/runs/spartan

To exit the Docker container:

  'exit' or Ctrl-d

Afterwards you probably also want to free up the system resouces by doing:

  docker rm gc


Good -- you're now all set for the GAMBIT tutorial :)



Docker cheat sheet
==================

- Download a Docker image from Docker Hub:

  docker pull <IMAGE NAME>
  
  Example:
  docker pull gambitbsm/gambit-tutorial


- List Docker images:

  docker images


- Start a new container in interactive mode and assign it a name:

  docker run -it --name <CHOOSE CONTAINER NAME> <IMAGE NAME>

  - Add --rm to automatically remove the container once you exit.
  - Add -v <HOST DIR>:<CONTAINER DIR> to set up a shared directory. 
   
  Example:
  docker run -it --rm --name gc -v $PWD/shared:/work/gambit/shared gambitbsm/gambit-tutorial


- List all containers:
    
  docker ps -a


- Exit a container (from within the container):
    
  'exit' or Ctrl-d


- Detach from container: 

  Ctrl-p Ctrl-q


- Reattach to container:

  docker attach <CONTAINER NAME>


- Stop a container (from outside the container):
    
  docker stop <CONTAINER NAME>


- Delete a container to free up resources:
  (Don't worry, you're not deleting the downloaded image.)

  docker container rm <CONTAINER NAME>

  Example:
  docker rm gc


- Delete all containers:
    
  docker container prune


- Copy files and folders from a container to your filesystem:

  docker cp <CONTAINER NAME>:/path/on/container /path/on/your/filesystem/

  Example:
  docker cp gc:/work/gambit/yaml_files/spartan.yaml ./

  (It may be easier to just set up a shared folder by using the -v flag
  when calling 'docker run'.)