From cddf30092b9d98530b51c5e991e2c8d00d42fc22 Mon Sep 17 00:00:00 2001 From: Ryan Schroder Date: Fri, 13 Dec 2019 14:55:03 -0600 Subject: [PATCH] Docker image guide Added steps to setting up, creating, and running spyglass in Docker image Change-Id: Ib168c12306608d19df66fc7961d1ceb28d46f5f1 --- README.rst | 1 - doc/source/cli.rst | 16 ------- doc/source/developer_quickstart.rst | 16 ------- doc/source/docker_guide.rst | 70 +++++++++++++++++++++++++++++ doc/source/getting_started.rst | 36 +++++---------- doc/source/index.rst | 18 +------- 6 files changed, 84 insertions(+), 73 deletions(-) create mode 100644 doc/source/docker_guide.rst diff --git a/README.rst b/README.rst index 697807b..06a16bf 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,3 @@ - What is Spyglass? ----------------- diff --git a/doc/source/cli.rst b/doc/source/cli.rst index f475709..a59504f 100644 --- a/doc/source/cli.rst +++ b/doc/source/cli.rst @@ -1,19 +1,3 @@ -.. - Copyright 2019 AT&T Intellectual Property. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - ============ Spyglass CLI ============ diff --git a/doc/source/developer_quickstart.rst b/doc/source/developer_quickstart.rst index ab47e68..1ff9855 100644 --- a/doc/source/developer_quickstart.rst +++ b/doc/source/developer_quickstart.rst @@ -1,19 +1,3 @@ -.. - Copyright 2019 AT&T Intellectual Property. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - ========================== Developer Quickstart Guide ========================== diff --git a/doc/source/docker_guide.rst b/doc/source/docker_guide.rst new file mode 100644 index 0000000..c070733 --- /dev/null +++ b/doc/source/docker_guide.rst @@ -0,0 +1,70 @@ +================================== +Running Spyglass in a Docker Image +================================== + +This is a guide to creating a docker image locally and running Spyglass in the +docker image. + +1. Before creating the Spyglass image, ensure you have cloned Spyglass_, +`Spyglass Excel plugin`_, and that you have installed `Docker CE`_. + +2. Update the Makefile with desired Linux distribution:: + + DISTRO=(ubuntu_xenial or ubuntu_bionic or opensuse_15) + +3. If necessary, change the PROXY variable to your proxy and change the +USE_PROXY to true in the Makefile. + +4. Go to the Spyglass directory in Terminal and run ``make images``. When the +build is done, you will see ``Successfully built `` + +5. From your home directory, create a new directory to store the output from +docker with the following command: + +.. code-block:: bash + + mkdir -p ~/tmp/spyglass + +6. Run Spyglass with the following command. The -v tag is used to mount the +necessary local folders to the docker image . You must use the full path to the +local folders you are mounting to. The path following the ':' is a path inside +the docker container. These folders will be made automatically by docker. (The +directory you are mounting to must be 'mnt' or another directory owned by +airship user in the docker image) + +.. code-block:: bash + + docker run -v /path/to/input/files:/mnt/input \ + -v ~/tmp/spyglass:/mnt/output \ + spyglass excel documents -i \ + -x /mnt/input/ \ + -e /mnt/input/ \ + -c /mnt/input/ \ + -s -t /mnt/input/ \ + -d /mnt/output -m /mnt/output + +Example +^^^^^^^ +The following shows the command used to create the site manifest and +intermediary in the docker container using the example files provided in +Spyglass and the Spyglass Excel Plugin. (``/root/path/`` is the path to +spyglass in your directory) + +.. code-block:: bash + + docker run \ + -v /root/path/spyglass/spyglass/examples/:/mnt/examples \ + -v /root/path/spyglass-plugin-xls/spyglass_plugin_xls/examples:/mnt/examples_xls \ + -v ~/tmp/spyglass:/mnt/output \ + spyglass excel documents -i \ + -x /mnt/examples_xls/SiteDesignSpec_v0.1.xlsx \ + -e /mnt/examples_xls/excel_spec.yaml \ + -c /mnt/examples/site_config.yaml \ + -s airship-seaworthy \ + -t /mnt/examples/templates \ + -d /mnt/output/ \ + -m /mnt/output/ + +.. _Spyglass: getting_started.html#basic-usage +.. _`Spyglass Excel Plugin`: https://opendev.org/airship/spyglass-plugin-xls/src/branch/master/doc/source/getting_started.rst +.. _`Docker CE`: https://docs.docker.com/install/ \ No newline at end of file diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index 9de9223..2ea6908 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -1,19 +1,3 @@ -.. - Copyright 2019 AT&T Intellectual Property. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - =============== Getting Started =============== @@ -65,11 +49,11 @@ Architecture Supported Features ------------------ -1. Spyglass Excel Plugin: https://opendev.org/airship/spyglass-plugin-xls +1. `Spyglass Excel Plugin `_ Future Work ----------- -1) Schema based manifest generation instead of Jinja2 templates. It shall +1. Schema based manifest generation instead of Jinja2 templates. It shall be possible to cleanly transition to this schema based generation keeping a unique mapping between schema and generated manifests. Currently this is managed by considering a mapping of j2 templates with schemas and site type. @@ -120,16 +104,20 @@ Basic Usage Before using Spyglass you must: -1. Clone the Spyglass repository: +1. Clone the Spyglass repository:: - .. code-block:: console + git clone https://opendev.org/airship/spyglass.git - git clone https://opendev.org/airship/spyglass.git +2. Install the required packages in Spyglass:: -2. Install the required packages in Spyglass: + pip3 install pipenv && pipenv install - .. code-block:: console +3. Launch the pipenv from your Spyglass directory:: - pip3 install pipenv && pipenv install + pipenv shell + +4. Install Spyglass into the pipenv:: + + pip3 install . .. _airship-specs: https://airshipit.readthedocs.io/projects/specs/en/latest/specs/1.x/approved/data_config_generator.html \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 923e89b..de00840 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,19 +1,3 @@ -.. - Copyright 2019 AT&T Intellectual Property. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - ====================== Spyglass Documentation ====================== @@ -45,4 +29,6 @@ engineer modify any data if required. getting_started developer_quickstart cli + docker_guide + .. _spyglass-plugin-xls: https://opendev.org/airship/spyglass-plugin-xls \ No newline at end of file