From 1383b7ca7fc4c734c441eb49d66296463002ba00 Mon Sep 17 00:00:00 2001
From: Jeremy Fee <jmfee@usgs.gov>
Date: Fri, 13 Mar 2020 11:27:40 -0600
Subject: [PATCH] Add pip, links to develop and docker to install. Update
docker docs
---
Dockerfile | 7 +++--
docker-entrypoint.sh | 15 +--------
docs/install.md | 40 ++++++++++++++++--------
docs/install_docker.md | 69 ++++++++++++++++++++----------------------
4 files changed, 65 insertions(+), 66 deletions(-)
diff --git a/Dockerfile b/Dockerfile
index 7dabf4b0b..6bbdf3350 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -39,11 +39,12 @@ RUN useradd \
-r \
-s /sbin/nologin \
geomag_user \
- && mkdir -p /home/geomag_user/notebooks \
- && chown -R geomag_user:geomag_user /home/geomag_user
+ && mkdir -p /data \
+ && chown -R geomag_user:geomag_user /data
USER geomag_user
-WORKDIR /geomag-algorithms
+WORKDIR /data
EXPOSE 8000
+
# entrypoint needs double quotes
ENTRYPOINT [ "/geomag-algorithms/docker-entrypoint.sh" ]
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
index 88e66799c..14037016d 100755
--- a/docker-entrypoint.sh
+++ b/docker-entrypoint.sh
@@ -1,24 +1,11 @@
#! /bin/bash
-# run jupyter in the background, and forward SIGTERM manually.
-# "exec" seems like a much simpler solution for this,
-# however, jupyter kernels die noisy deaths when using exec.
-
-# _term () {
-# echo 'Caught SIGTERM'
-# kill -TERM "$child"
-#}
-#trap _term SIGTERM
-
# add geomagio to notebook path
export PYTHONPATH=/geomag-algorithms
# run jupyter notebook server
exec jupyter notebook \
--ip='*' \
- --notebook-dir=/home/geomag_user/notebooks \
+ --notebook-dir=/data \
--no-browser \
--port=8000
-
-#child=$!
-#wait "$child"
diff --git a/docs/install.md b/docs/install.md
index 9c7b6dd04..2217fb736 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,26 +1,42 @@
-Installation
-============
+# Installation
+> - [Develop](./develop.md) describes how to install locally.
+> - [Docker](./install_docker.md) describes container usage.
+## Requirements:
-1) Install Python and dependencies (obspy and pycurl)
+- Python 3.6 or newer
+- ObsPy 1.2.1 or newer
- Using Anaconda is recommended ( https://conda.io/miniconda.html ).
+## Procedure:
- conda env create -f geomagenv.yml
- source activate geomagenv
+1. Install Python and dependencies
- or
+ - Option 1: Anaconda/Miniconda (https://conda.io/miniconda.html):
- conda create --name=geomagenv --channel conda-forge python=3 obspy pycurl
- source activate geomagenv
+ conda create --name=geomagenv --channel conda-forge python=3 obspy pycurl
+ source activate geomagenv
-2) Install **geomagio**
+ - Option 2: Pip
- pip install git+https://github.com/usgs/geomag-algorithms.git
+ > `pyenv` can install specific/multiple versions of python
+ >
+ > - https://github.com/pyenv/pyenv
+ > - https://github.com/pyenv-win/pyenv-win
+
+ # create virtual environment (optional)
+ python -m venv path/to/geomagenv
+ source path/to/geomagenv/bin/activate
+
+ # install dependencies
+ pip install numpy
+ pip install obspy
+2. Install **geomagio**
+
+ pip install git+https://github.com/usgs/geomag-algorithms.git
-3) Use **geomagio**
+3. Use **geomagio**
- Use the main script, `geomag.py -h`
- In python scripts, `import geomagio`
diff --git a/docs/install_docker.md b/docs/install_docker.md
index 1571d1f17..ffe0b5312 100644
--- a/docs/install_docker.md
+++ b/docs/install_docker.md
@@ -1,60 +1,55 @@
## Docker
+
https://www.docker.com/
Docker containers bundle all dependencies needed to use geomag-algorithms.
The container includes a Jupyter Notebook server for interactive development.
-> Docker images are built using the `Dockerfile` at the root of this project.
+### Run docker container
+> This page provides one example of how to run a container. See https://docs.docker.com/engine/reference/run/ for detailed `docker run` documentation.
-### Create a new docker container
+The following command creates and starts a container in the background.
-The following command creates and starts a container.
-```
-docker run -d --name geomagio -p 8000:80 usgs/geomag-algorithms
-```
+ docker run -rm -it --name geomagio -p 8000:8000 -v $(pwd)/data:/data usgs/geomag-algorithms
-- `-d` runs container in the background
+- `-rm` runs a temporary container
+- `-it` makes the container interactive (so you can stop it with `ctrl+c`)
- `-name geomagio` assigns the name `geomagio`
-- `-p 8000:80` forwards system port `8000` to container port `80`
+- `-p 8000:8000` forwards system port `8000` to container port `8000`
+- `-v $(pwd)/data:/data` mounts a local data directory (./data) into the container so notebooks are saved
- `usgs/geomag-algorithms:latest` refers to the
latest version of the geomag-algorithms docker image
- > Notebooks are stored in the container in the directory
- > `/home/geomag_user/notebooks`
-
-
### Use the container
-- Start a stopped container:
-```
-docker start geomagio
-```
-
- Run an interactive python prompt
-```
-docker exec -it geomagio python
-```
+
+
+ docker exec -it geomagio python
- Use the Jupyter Notebook server
-```
-open http://localhost:8000/
-```
+
+ Check the output for a URL like this, that can be opened in a web browser: `http://127.0.0.1:8000/?token=...`
- Use the `geomag.py` command line interface
-```
-docker exec -it geomagio geomag.py \
- --inchannels H E Z F \
- --input edge \
- --interval minute \
- --observatory BOU \
- --output iaga2002 \
- --output-stdout \
- --starttime 2016-07-04T00:00:00Z \
- --endtime 2016-07-04T23:59:00Z
-```
+
+ docker exec -it geomagio geomag.py \
+ --inchannels H E Z F \
+ --input edge \
+ --interval minute \
+ --observatory BOU \
+ --output iaga2002 \
+ --output-stdout \
+ --starttime 2016-07-04T00:00:00Z \
+ --endtime 2016-07-04T23:59:00Z
- Stop a running container:
-```
-docker stop geomagio
-```
+
+ Press `Ctrl+C` and follow prompts to stop the container.
+
+### Build container
+
+Docker images are built using the `Dockerfile` at the root of this project.
+
+ docker build -t usgs/geomag-algorithms:TAG .
--
GitLab