Browse Source

Docker image guide

Added steps to setting up, creating, and running spyglass in Docker image

Change-Id: Ib168c12306608d19df66fc7961d1ceb28d46f5f1
changes/16/699016/11
Ryan Schroder 3 years ago committed by Schroder, Ryan (rs530b)
parent
commit
cddf30092b
  1. 1
      README.rst
  2. 16
      doc/source/cli.rst
  3. 16
      doc/source/developer_quickstart.rst
  4. 70
      doc/source/docker_guide.rst
  5. 36
      doc/source/getting_started.rst
  6. 18
      doc/source/index.rst

1
README.rst

@ -1,4 +1,3 @@
What is Spyglass?
-----------------

16
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
============

16
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
==========================

70
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 <DOCKER_IMAGE>``
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 \
<DOCKER_IMAGE> spyglass excel documents -i \
-x /mnt/input/<excel_file_name> \
-e /mnt/input/<excel_spec_name> \
-c /mnt/input/<site_config_name> \
-s <site_name> -t /mnt/input/<templates_folder> \
-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 \
<DOCKER_IMAGE> 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/

36
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 <https://opendev.org/airship/spyglass-plugin-xls>`_
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::
git clone https://opendev.org/airship/spyglass.git
2. Install the required packages in Spyglass::
.. code-block:: console
pip3 install pipenv && pipenv install
git clone https://opendev.org/airship/spyglass.git
3. Launch the pipenv from your Spyglass directory::
2. Install the required packages in Spyglass:
pipenv shell
.. code-block:: console
4. Install Spyglass into the pipenv::
pip3 install pipenv && pipenv install
pip3 install .
.. _airship-specs: https://airshipit.readthedocs.io/projects/specs/en/latest/specs/1.x/approved/data_config_generator.html

18
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
Loading…
Cancel
Save