start of user tooling post

_posts/2019-11-20-tooling.md

@@ -0,0 +1,82 @@
+---
+layout: post
+title: "Setting up a local copy of the book"
+---
+
+In the spirit of [open science](https://www.fosteropenscience.eu/content/what-open-science-introduction), we are not only writing this book in the open, but also hoping to tap into
+[user-led innovation](https://innovationmanagement.se/2011/02/21/eric-von-hippel-on-innovation/). Towards that end, we want to give interested users the ability to setup the tooling
+to run the book locally on their own machines.
+
+We have developed a docker container that has all the software packages and instructions for building the book. Rather than having to install all these packages independently on your operating system, the container bundles all of these for us. Docker will enable you to run this container inside your host operating system.
+
+Below we outline the instructions for setting up your machine and running the container. 
+
+
+## Assumptions
+
+ 1. You have admin rights over your machine
+ 2. You are running either Windows 10 Pro, macOS, or Linux
+
+
+## Installing Docker
+
+### Windows
+
+[Install Docker Desktop for Windows](https://docs.docker.com/v17.09/engine/installation/)
+
+### macOS
+[Get started with Docker Desktop for Max](https://docs.docker.com/docker-for-mac/)
+
+### Linux
+
+[Get Docker Engine - Community for Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/)
+
+## Installing the Docker Container
+
+To install the prebuilt docker container for the book project, open a terminal under your host operating system:
+
+- **Windows**: we recommend [Powershell](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/powershell)
+- **macOS**: the Terminal app (`/Applications/Utilities/Terminal.app`) is a great option
+- **Linux**: any default console provided by your distribution of choice will be good
+
+Once you are on the terminal, run the following command to download the container to your own machine:
+
+```
+docker pull gdsbook/stack
+```
+
+Note this will take a while and will require a significant amount of bandwith (the entire image is about 8GB).
+
+## Acquire book source materials
+
+In order to work with the book locally, you need to acquire the source files. There are two ways to do so. . If you are familiar with [git](https://github.com/) you can clone the repository with:
+
+```
+git clone git@github.com:gdsbook/book.git
+```
+
+This will create a directory named `gdsbook` under the current working directory.
+
+If you do not want to use git, you can download the source files in a zip archive by selecting <https://github.com/gdsbook/book/archive/master.zip>.
+
+Once downloaded, extract the files and rename the resulting directory. On Linux or macOS you would do:
+```
+> unzip book-master.zip
+> mv book-master gdsbook
+```
+
+
+## Running the Container
+At this point you are ready to work with the book. Be sure you are in the parent directory above the `gdsbook` directory created in the previous step.
+
+ To get started, you will run a
+[Jupyter](https://jupyter.org/) session from the same terminal used above, as follows:
+
+```
+ > docker run --rm -ti -p 8888:8888 -v ${PWD}:/home/jovyan/work gdsbook
+```
+
+This will start a Python session, please do not quite the window until you are done using Python!
+
+
+