Merge pull request #15 from tostt/docker

Dockerfile with instructions
grst · Jun 10, 2019 · aef2cf5 · aef2cf5
2 parents 5683dd2 + d72475e
commit aef2cf5
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 0 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,5 @@
+FROM continuumio/miniconda3
+COPY . .
+RUN python setup.py install 
+RUN export GEOS_VERSION="$(python setup.py --version)" \
+    && ln -s /opt/conda/lib/python3.7/site-packages/geos-"$GEOS_VERSION"-py3.7.egg/geos /opt/conda/lib/python3.7/site-packages/geos
diff --git a/doc/users.md b/doc/users.md
@@ -1,5 +1,7 @@
 ## Installation
 
+Instructions for running GEOS in a docker container can be found [below](#running-geos-in-a-docker-container).
+
 ### Requirements
 GEOS is python3 only. If you don't have python, I recommend downloading
 [Anaconda Python](https://www.continuum.io/downloads).
@@ -136,3 +138,90 @@ GEOS supports Mapsources which consist of multiple layers. Such a file looks as
    </layers>
 </customMultiLayerMapSource>
 ```
+
+### Running GEOS in a docker container
+If you are planning to run GEOS in a docker container, there is no requirement apart from having docker installed on your host. No install of python is necessary.
+
+Running GEOS involves building a GEOS image, a one-time operation, and running a container when needed.
+
+1. **Getting a Dockerfile**
+
+When running GEOS in docker, you have 2 options:
+- running the GEOS pip package release
+- running GEOS built from source code
+
+This choice will lead to using different Dockerfiles, as explained below.
+
+**Option a):** using the pip release of GEOS
+
+You do not need to download the GEOS sources. You only need to create a Dockerfile with the following contents:
+```dockerfile
+FROM continuumio/miniconda3
+RUN pip install geos
+```
+
+**Option b):** building GEOS from source code
+
+The GEOS sources already contain the appropriate Dockerfile. Download the sources with
+```sh
+git clone https://github.com/grst/geos.git
+```
+
+2. **Building the GEOS docker image**
+
+To build the docker image, move to the directory where the Dockerfile is and run :
+```sh
+docker build -t geos .
+```
+3. **Running the GEOS container**
+
+Run (on a single line) :
+```sh
+docker run
+--rm
+-p <server_port>:5000
+--mount type=bind,source=<server_mapsources_directory>,target=/opt/conda/lib/python3.7/site-packages/geos/mapsources
+geos
+geos --host 0.0.0.0 --display-host <server_ip>
+```
+
+You will have to substitute the following variables with values that are relevant to your setup :
+
+| Variable                          |Meaning                                         |Example|
+|-----------------------------------|------------------------------------------------|----|
+|`<server_port>`                |Port used to reach the server                   |`5000`|
+|`<server_mapsources_directory>`|Path to the `mapsources` directory on the server|`/home/user/me/mapsources`|
+|`<server_ip>`                  |IP adress of the server                         |`192.168.0.1` / See note below|
+
+Note:
+* On Linux systems, ```<server_ip>``` can be found by running ```ip route get 1 | awk '{print $NF;exit}'```
+
+4. **Bonus: Building and running the GEOS container with docker-compose**
+
+For ease of use, you can completely avoid using the docker *build* and *run* commands by creating a **docker-compose.yml** file next to the Dockerfile. Its contents can be similar to the following :
+
+```docker-compose
+version: '3.7'
+services:
+    geos:
+        build: .
+        image: geos
+        container_name: geos
+        ports:
+            - '5000:5000'
+        volumes:
+            - //c/Users/me/Documents/mapsources:/opt/conda/lib/python3.7/site-packages/geos/mapsources
+        command: geos --host 0.0.0.0
+```
+Note: The above file demonstrates the use of a Windows path for the *mapsources* host directory.
+
+You can then start GEOS by issuing
+```sh
+docker-compose up
+```
+This command will take care of building the GEOS image if it does not exist locally.
+
+You can stop GEOS by issuing
+```sh
+docker-compose down
+```