Create how-to-run-on-windows

docs/how-to-run-on-windows.md

@@ -0,0 +1,58 @@
+# BOINC project windows cookbook (with `boinc-server-docker`)
+
+## Requirements
+
+If you are hosting your server on a Linux machine, the requirements are,
+
+* [Docker](https://docs.docker.com/engine/installation/) (>=17.03.0ce)
+* [docker-compose](https://docs.docker.com/compose/install/) (>=1.13.0 but !=1.19.0 due to a [bug](https://github.com/docker/docker-py/issues/1841))
+* git
+
+(Note that Docker requires a 64-bit machine and Linux kernel newer than version 3.10)
+
+If your are hosting your server on Windows, you should use either,
+
+* [Docker for Windows](https://docs.docker.com/docker-for-windows/install/) (>=17.06.0ce)
+
+If you Windows system is too old to run either of those, you can use instead, 
+
+* [Docker Toolbox](https://docs.docker.com/toolbox/overview) (>=17.05.0ce)
+
+There are no other dependencies, as everything else is packaged inside of Docker. 
+
+The server itself runs Linux. On Windows, Docker does the job of transparently virtualizing a Linux machine for you. The commands given in this guide should be run from your system's native terminal, unless you are running Docker Toolbox, in which case they should be run from the "Docker Quickstart Terminal" (and on Windows you will need to add `.exe` to the end, e.g. `docker.exe` instead of `docker`).
+
+
+## Docker lightning intro
+
+Docker is kind of like a virtual machine in that it packages up a program, its dependencies, and in fact an entire operating system, into a self contained and isolated unit. It's not actually a virtual machine though. For example, it doesn't run any slower than if you were running the programs natively. 
+
+Some terminology: A Docker **image** (like a virtual machine image) contains the operating system and its entire filesystem. Images have names that look like "debian" or "ubuntu:16.04". The part after the ":" specifies the version (the default is "latest", so "debian" and "debian:latest" are the same thing). A running image is called a **container**; you can run multiple containers from a given image (i.e. multiple instances). Unlike most virtual machines, when you stop a container, any changes to files are lost. To persist files between runs, Docker uses **volumes**. A Docker volume is just a folder. It can be mounted at any location inside a container, and it can be mounted in multiple containers at once. Files changed inside volumes are saved. 
+
+Finally, Docker provides a free public repository for hosting images called the Docker Hub. You **pull** and **push** images to and from Docker Hub. This is how we distribute the `boinc-server-docker` images. Most images on the Docker Hub start with a repository name, e.g. our repository is called "boinc" so the full image names look like "boinc/server_apache:latest". 
+
+Docker images are created by writing a **Dockerfile** which specifies a base image to start from and a set of normal Linux commands which are run on top of the image to create a new one. When you create your own server, you will start from a base image provided by `boinc-server-docker` (which already includes all of the BOINC software), and you will write a Dockerfile which adds just your customizations, (e.g. your custom web pages, your applications,  etc...)
+
+
+## Launching a test server
+
+Before creating your real project, lets launch a sample test server to see how it works. To do this, get the `boinc-server-docker` source code, 
+
+```bash
+git clone https://github.com/marius311/boinc-server-docker.git
+cd boinc-server-docker
+```
+
+and then run,
+
+```bash
+docker-compose pull
+docker-compose up -d
+docker-compose exec apache bash
+ln -s /home/boincadm/project/boincserver.httpd.conf /etc/apache2/conf-enabled/boincserver.httpd.conf
+/etc/init.d/apache2 reload
+bin/stop
+bin/start
+```
+
+You now have a running BOINC server!