diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000000000000000000000000000000000000..14a369920a936e0a44fe853e38cbd7fef367a6c1
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,4 @@
+.DS_Store
+node_modules
+*.pyc
+conf
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000000000000000000000000000000000000..c53f469e5fbaf3fc18718a54f94930561b3ac0f4
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,64 @@
+FROM debian:jessie
+
+MAINTAINER Jeremy Fee <jmfee@usgs.gov>
+LABEL usgs.geomag-algorithms.version=0.2.0
+
+
+# update os
+
+RUN apt-get update --fix-missing && \
+ apt-get install -y --no-install-recommends \
+ bzip2 \
+ ca-certificates \
+ curl \
+ gcc \
+ libcurl4-gnutls-dev \
+ libglib2.0-0 \
+ libgnutls28-dev \
+ libsm6 \
+ libxext6 \
+ libxrender1 && \
+ apt-get clean
+
+
+ENV PATH /conda/bin:$PATH
+
+# install conda and install obspy
+RUN echo 'export PATH=/conda/bin:$PATH' > /etc/profile.d/conda.sh && \
+ curl https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh \
+ -o ~/miniconda.sh && \
+ /bin/bash ~/miniconda.sh -b -p /conda && \
+ rm ~/miniconda.sh && \
+ conda config --add channels obspy && \
+ conda install --yes jupyter obspy && \
+ conda clean -i -l -t -y && \
+ pip install pycurl
+
+
+# copy library (ignores set in .dockerignore)
+COPY . /geomag-algorithms
+
+
+RUN pip install /geomag-algorithms && \
+ groupadd \
+ -g 1234 \
+ -r \
+ geomag_user && \
+ useradd \
+ -c 'Docker image user' \
+ -d /home/geomag_user \
+ -g geomag_user \
+ -r \
+ -s /sbin/nologin \
+ -u 1234 \
+ geomag_user && \
+ mkdir -p /home/geomag_user/notebooks && \
+ chown -R geomag_user:geomag_user /home/geomag_user
+
+
+USER geomag_user
+
+WORKDIR /home/geomag_user
+EXPOSE 80
+# entrypoint needs double quotes
+ENTRYPOINT [ "/geomag-algorithms/docker-entrypoint.sh" ]
diff --git a/LICENSE.md b/LICENSE.md
index 77620d32ea791e385f2bf4ed3718c21cff0708db..58fc160d28b191cf7158a016c853a8c063ead65e 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -3,3 +3,21 @@ contains materials that originally came from the United States Geological
Survey, an agency of the United States Department of Interior. For more
information, see the official USGS copyright policy at
http://www.usgs.gov/visual-id/credit_usgs.html#copyright
+
+
+Disclaimers
+-----------
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Information provided by this software may be preliminary or provisional and is
+subject to revision. It is being provided to meet the need for timely best
+science. The information has not received final approval by the U.S. Geological
+Survey (USGS) and is provided on the condition that neither the USGS nor the
+U.S. Government shall be held liable for any damages resulting from the
+authorized or unauthorized use of the information.
diff --git a/README.md b/README.md
index 38ac259af87769a2914e0a61fb2d99b70f3da2b7..b46b932752a185684307e3f7a029ca09abaa50df 100644
--- a/README.md
+++ b/README.md
@@ -3,51 +3,125 @@ Geomag Algorithms
[](https://travis-ci.org/usgs/geomag-algorithms)
-Geomag algorithms includes tools to fetch, process, and output geomag data.
+Geomag Algorithms is an open source library for processing
+Geomagnetic timeseries data. It includes algorithms and input/output factories
+used by the [USGS Geomagnetism Program](http://geomag.usgs.gov) to
+ translate between data formats,
+ generate derived data and indices in near-realtime,
+ and research and develop new algorithms.
+
+
+- Accesses USGS data services.
+- Built using established open source python libraries
+ [NumPy](http://www.numpy.org/),
+ [SciPy](http://www.scipy.org/), and
+ [ObsPy](http://www.obspy.org/).
+- Common geomagnetic formats including
+ IAGA2002,
+ IMFV122,
+ IMFV283 (read only), and
+ PCDCP.
+- Defines command line interface, `geomag.py`.
+- Embeddable Python API, `import geomagio`.
+
+
+## Examples
+> [More Examples in docs/example/](./docs/example/)
+
+The following examples request data from USGS for
+ `BOU` observatory,
+ `H`, `E`, `Z`, and `F` component,
+ `minute` interval,
+ and `variation` type data
+ for the day `2016-07-04`,
+then write `IAGA2002` formatted output to the console.
+
+### Command Line Interface Example
+```
+geomag.py \
+ --input edge \
+ --observatory BOU \
+ --inchannels H E Z F \
+ --type variation \
+ --interval minute \
+ --output iaga2002 \
+ --output-stdout \
+ --starttime 2016-07-04T00:00:00Z \
+ --endtime 2016-07-04T23:59:00Z
+```
+[Command Line Interface documentation](./docs/cli.md)
+
+### Python API Example
+```
+import sys
+import geomagio
+from obspy.core import UTCDateTime
+
+input_factory = geomagio.edge.EdgeFactory()
+timeseries = input_factory.get_timeseries(
+ observatory = 'BOU',
+ channels = ('H', 'E', 'Z', 'F'),
+ type = 'variation',
+ interval = 'minute',
+ starttime = UTCDateTime('2016-07-04T00:00:00Z'),
+ endtime = UTCDateTime('2016-07-04T23:59:00Z'))
+
+output_factory = geomagio.iaga2002.IAGA2002Factory()
+output_factory.write_file(
+ channels = ('H', 'E', 'Z', 'F'),
+ fh = sys.stdout,
+ timeseries = timeseries)
+```
+[Python API documentation](./docs/api.md)
+
+
+## Install
+> [More Install options in docs/install.md](./docs/install.md).
+
+### Docker
+Docker is the simplest install option.
+
+1. Create and start a new container
+
+ named `geomagio`,
+ listening on local port `8000`,
+ from the image `usgs/geomag-algorithms` on docker hub
+ ```
+ docker run -d --name geomagio -p 8000:80 usgs/geomag-algorithms
+ ```
+2. Use the running container
+
+ - Run the `geomag.py` command line interface:
+ ```
+ docker exec -it geomagio geomag.py
+ ```
+ - Run python interactively in a web browser:
+ ```
+ open http://localhost:8000
+ ```
+ > In the top right corner, choose "New" then "Python 2"
+
+
+## Algorithms
+[Algorithms described in docs/algorithms/](./docs/algorithms)
+
+
+## Developing
+[Developing described in docs/develop.md](./docs/develop.md).
+
+
+## License
+[License described in LICENSE.md](./LICENSE.md)
+
+
+## Problems or Questions?
+
+- [Report an issue using the GitHub issue tracker](http://github.com/usgs/geomag-algorithms/issues)
+- [Join the USGS geomag-data mailing list](https://geohazards.usgs.gov/mailman/listinfo/geomag-data)
+- [Email jmfee at usgs.gov](mailto:jmfee@usgs.gov)
+
+
+## Additional Links
-
-## Getting Started
-
-### [Install](./docs/install.md)
-First time install. Walk through dependencies and other considerations.
-
-Document: [/docs/install.md](./docs/install.md)
-
-
-### [Command Line Usage](./docs/usage.md)
-Details and examples for proper usage. Get started quickly.
-
-Basic usage:
-
- - Use the main script, `geomag.py -h`
- - In python scripts, `import geomagio`
-
-Document: [/docs/usgage.md](./docs/usage.md)
-
-
-### [Python API](./docs/api.md)
-API Overview and examples for using the geomag-algorithms project in python.
-
-Document: [/docs/api.md](./docs/api.md)
-
-
-### [Develop](./docs/develop.md)
-Development dependencies discussed here. Project is built with Grunt and Node
-and is written primarily in Python 2.7.
-
-Document: [/docs/develop.md](./docs/develop.md)
-
-
-## Supported Formats
-
-- [Edge](./docs/io.md#Edge)
-- [IAGA2002](./docs/io.md#IAGA2002)
-- [IMFV283 (Input only)](./docs/io.md#IMFV283)
-- [PCDCP](./docs/io.md#PCDCP)
-
-
-## Supported Algorithms
-
-- [DeltaF](./docs/algorithms/DeltaF_usage.md)
-- [SqDist](./docs/algorithms/SqDist_usage.md)
-- [XYZ](./docs/algorithms/XYZ_usage.md)
+- [USGS Geomagnetism Program Home Page](http://geomag.usgs.gov/)
+- [Waffle Project Board](https://waffle.io/usgs/geomag-algorithms)
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
new file mode 100755
index 0000000000000000000000000000000000000000..14f4954d147b505599e20b383b51e81740e49cd2
--- /dev/null
+++ b/docker-entrypoint.sh
@@ -0,0 +1,22 @@
+#! /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 SIGERM'
+ kill -TERM "$child"
+}
+trap _term SIGTERM
+
+
+# run jupyter notebook server
+jupyter notebook \
+ --ip='*' \
+ --notebook-dir=/home/geomag_user/notebooks \
+ --no-browser \
+ --port=8000 &
+
+child=$!
+wait "$child"
diff --git a/docs/install_docker.md b/docs/install_docker.md
new file mode 100644
index 0000000000000000000000000000000000000000..1571d1f17b7697baaeaf17e91f0f25b227325404
--- /dev/null
+++ b/docs/install_docker.md
@@ -0,0 +1,60 @@
+## 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.
+
+
+### Create a new docker container
+
+The following command creates and starts a container.
+```
+docker run -d --name geomagio -p 8000:80 usgs/geomag-algorithms
+```
+
+- `-d` runs container in the background
+- `-name geomagio` assigns the name `geomagio`
+- `-p 8000:80` forwards system port `8000` to container port `80`
+- `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
+```
+
+- Use the Jupyter Notebook server
+```
+open http://localhost:8000/
+```
+
+- 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
+```
+
+- Stop a running container:
+```
+docker stop geomagio
+```