You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by da...@apache.org on 2018/10/29 15:25:18 UTC
[trafficcontrol] 02/03: Added CIAB documentation
This is an automated email from the ASF dual-hosted git repository.
dangogh pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
commit 153e1b877a1246ca55ff4d2cc456ede56c5e619c
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Tue Oct 23 09:37:38 2018 -0600
Added CIAB documentation
---
docs/source/admin/quick_howto/ciab.rst | 117 +++++++++++++++++++++
docs/source/admin/quick_howto/index.rst | 24 ++---
.../cdn-in-a-box/traffic_router/Dockerfile | 18 ++--
3 files changed, 134 insertions(+), 25 deletions(-)
diff --git a/docs/source/admin/quick_howto/ciab.rst b/docs/source/admin/quick_howto/ciab.rst
new file mode 100644
index 0000000..d02b311
--- /dev/null
+++ b/docs/source/admin/quick_howto/ciab.rst
@@ -0,0 +1,117 @@
+..
+..
+.. 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.
+..
+
+.. _ciab:
+
+************
+CDN in a Box
+************
+"CDN in a Box" is a name given to the time-honored tradition of new Traffic Control developers/potential users attempting to set up their own miniature CDN to just see how it all fits together. Historically, this has been a nightmare of digging through leftover ``virsh`` scripts and manually configuring pretty hefty networking changes (don't even get me started on DNS) and just generally having a bad time. For a few years now, different people had made it to various stages of merging the [...]
+
+Getting Started
+===============
+Because it runs in Docker, the only true prerequisites are:
+
+* Docker version >= 17.05.0-ce
+* Docker Compose\ [1]_ version >= 1.9.0
+
+Building
+--------
+The CDN in a Box directory is found within the Traffic Control repository at ``infrastructure/cdn-in-a-box/``. CDN in a Box relies on the presence of pre-built RPM files for the following Traffic Control components:
+
+* Traffic Monitor - at ``infrastructure/cdn-in-a-box/traffic_monitor/traffic_monitor.rpm``
+* Traffic Ops - at ``infrastructure/cdn-in-a-box/traffic_ops/traffic_ops.rpm``
+* Traffic Portal - at ``infrastructure/cdn-in-a-box/traffic_portal/traffic_portal.rpm``
+* Traffic Router - at ``infrastructure/cdn-in-a-box/traffic_router/traffic_router.rpm`` - also requires an Apache Tomcat RPM at ``infrastructure/cdn-in-a-box/traffic_router/tomcat.rpm``
+
+.. note:: These can also be specified via the ``RPM`` variable to a direct Docker build of the component - with the exception of Traffic Router, which instead accepts ``JDK8_RPM`` to specify a Java Development Kit RPM, ``TRAFFIC_ROUTER_RPM`` to specify a Traffic Router RPM, and ``TOMCAT_RPM`` to specify an Apache Tomcat RPM.
+
+These can all be supplied manually via the steps in :ref:`dev-building` (for Traffic Control component RPMs) or via some external source. Alternatively, the ``infrastructure/cdn-in-a-box/Makefile`` file contains recipes to build all of these - simply run ``make``\ [2]_ from the ``infrastructure/cdn-in-a-box/`` directory.
+Once all RPM dependencies have been satisfied, run ``docker-compose build`` from the ``infrastructure/cdn-in-a-box/`` directory to construct the images needed to run CDN in a Box.
+
+Usage
+-----
+In a typical scenario, if the steps in `Building`_ have been followed, all that's required to start the CDN in a Box is to run ``docker-compose up`` - optionally with ``-d`` to run without binding to the terminal - from the ``infrastructure/cdn-in-a-box/`` directory. This will start up the entire stack and should take care of any needed initial configuration. The services within the containers are exposed locally to the host on specific ports. These are configured within the ``infrastru [...]
+
+.. _ciab-service-info:
+.. table:: Service Info
+
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Service | Ports exposed and their usage | Username | Password |
+ +=================================+==============================================================+=======================================+===========================================+
+ | DNS | DNS name resolution on 9353 | N/A | N/A |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Edge Tier Cache | Apache Trafficserver HTTP caching reverse proxy on port 9000 | N/A | N/A |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Mid Tier Cache | Apache Trafficserver HTTP caching forward proxy on port 9100 | N/A | N/A |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Mock Origin Server | Example web page served on port 9200 | N/A | N/A |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Traffic Monitor | Web interface and API on port 80 | N/A | N/A |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Traffic Ops | Main API endpoints on port 6443, with a direct route to the | ``TO_ADMIN_USER`` in `variables.env`_ | ``TO_ADMIN_PASSWORD`` in `variables.env`_ |
+ | | Perl API on port 60443\ [3]_ | | |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Traffic Ops PostgresQL Database | PostgresQL connections accepted on port 5432 (database name: | ``DB_USER`` in `variables.env`_ | ``DB_USER_PASS`` in `variables.env`_ |
+ | | ``DB_NAME`` in `variables.env`_) | | |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Traffic Portal | Web interface on 443 (Javascript required) | ``TO_ADMIN_USER`` in `variables.env`_ | ``TO_ADMIN_PASSWORD`` in `variables.env`_ |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Traffic Router | Web interfaces on ports 3080 (HTTP) and 3443 (HTTPS), with a | N/A | N/A |
+ | | DNS service on 53 and an API on 3333 | | |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+ | Traffic Vault | Riak key-value store on port 8010 | ``TV_ADMIN_USER`` in `variables.env`_ | ``TV_ADMIN_PASSWORD`` in `variables.env`_ |
+ +---------------------------------+--------------------------------------------------------------+---------------------------------------+-------------------------------------------+
+
+.. seealso:: :ref:`tr-api` and :ref:`tm-api`
+
+While the components may be interacted with by the host using these ports, the true operation of the CDN can only truly be seen from within the Docker network. To see the CDN in action, connect to a container within the CDN in a Box project and use cURL to request the URL ``http://video.demo1.mycdn.ciab.test`` which will be resolved by the DNS container to the IP of the Traffic Router, which will provide a ``302 FOUND`` response pointing to the Edge-Tier cache. A typical choice for this [...]
+
+.. code-block:: shell
+ :caption: Example Command to See the CDN in Action
+
+ sudo docker-compose exec enroller /usr/bin/curl -L "http://video.demo1.mycdn.ciab.test"
+
+When the CDN is to be shut down, it is often best to do so using ``sudo docker-compose down -v`` due to the use of shared volumes in the system which might interfere with a proper initialization upon the next run.
+
+variables.env
+"""""""""""""
+.. include:: ../../../../infrastructure/cdn-in-a-box/variables.env
+ :code: shell
+ :start-line: 16
+ :tab-width: 4
+
+.. note:: While these port settings can be changed without hampering the function of the CDN in a Box system, note that changing a port without also changing the matching port-mapping in ``infrastructure/cdn-in-a-box/docker-compose.yml`` for the affected service *will* make it unreachable from the host.
+
+.. [1] It is perfectly possible to build and run all containers without Docker Compose, but it's not recommended and not covered in this guide.
+.. [2] Consider ``make -j`` to build quickly, if your computer can handle multiple builds at once.
+.. [3] Please do NOT use the Perl endpoints directly. The CDN will only work properly if everything hits the Go API, which will proxy to the Perl endpoints as needed.
+
+Advanced Usage
+==============
+This section will be amended as functionality is added to the CDN in a Box project.
+
+The Test Client
+---------------
+The "testclient" service is an optional extension to CDN in a Box which provides several more user-friendly interfaces to the CDN network. Specifically it contains:
+
+* A small HTTP proxy on port 7070
+* An SSH server listening on port 2200
+* A VNC server on port 5900
+* A Socks5 Proxy on port 9090
+
+Using this, the CDN can be directly utilized using the network's internal name resolution and a web browser. To use the test client, pass ``-f docker-compose.testclient.yml`` either to the same ``docker-compose`` command, or to a separate ``docker-compose`` command run after the CDN in a Box has already started. If the former is done, note that it is also necessary to pass ``-f docker-compose.yml`` to properly build the entire system along with the test client.
+
+.. seealso:: `The official Docker Compose documentation CLI reference <https://docs.docker.com/compose/reference/>`_ for complete instructions on how to pass service definition files to the ``docker-compose`` executable.
diff --git a/docs/source/admin/quick_howto/index.rst b/docs/source/admin/quick_howto/index.rst
index c6d05dc..65d3151 100644
--- a/docs/source/admin/quick_howto/index.rst
+++ b/docs/source/admin/quick_howto/index.rst
@@ -18,21 +18,13 @@ Quick How To Guides
*******************
Traffic Control is a complicated system, and documenting it is not trivial. Sometimes a picture says more than a thousand words, so here are some screen shot based tutorials on how to use some of the more involved features.
-Traffic Ops
-===========
-
-.. toctree::
-
- multi_site.rst
- federations.rst
- regionalgeo.rst
- anonymous_blocking.rst
-
-Traffic Portal
-==============
-
.. toctree::
- dnssec.rst
- ds_requests.rst
- steering.rst
+ multi_site
+ federations
+ regionalgeo
+ anonymous_blocking
+ dnssec
+ ds_requests
+ steering
+ ciab
diff --git a/infrastructure/cdn-in-a-box/traffic_router/Dockerfile b/infrastructure/cdn-in-a-box/traffic_router/Dockerfile
index c940165..ca158be 100644
--- a/infrastructure/cdn-in-a-box/traffic_router/Dockerfile
+++ b/infrastructure/cdn-in-a-box/traffic_router/Dockerfile
@@ -15,7 +15,7 @@
# specific language governing permissions and limitations
# under the License.
############################################################
-# Dockerfile to build Traffic Router 3.0
+# Dockerfile to build Traffic Router 3.0
# Based on CentOS 7.x
############################################################
@@ -25,12 +25,12 @@ MAINTAINER Dan Kirkwood
# Default values for TMCAT RPM and RPM -- override with `docker build --build-arg JDK=...'
ARG JDK8_RPM=http://download.oracle.com/otn-pub/java/jdk/8u181-b13/96a7b8442fe848ef90c96a2fad6ed6d1/jdk-8u181-linux-x64.rpm
ARG TRAFFIC_ROUTER_RPM=traffic_router/traffic_router.rpm
-ARG TOMCAT_RPM=traffic_router/tomcat.rpm
+ARG TOMCAT_RPM=traffic_router/tomcat.rpm
### Common for all sub-component builds
RUN yum -y install epel-release git rpm-build net-tools iproute nc wget tar unzip \
perl-JSON perl-WWWCurl which make autoconf automake gcc gcc-c++ apr apr-devel \
- openssl openssl-devel bind-utils net-tools perl-JSON-PP gettext && \
+ openssl openssl-devel bind-utils net-tools perl-JSON-PP gettext && \
yum -y clean all
ADD $TRAFFIC_ROUTER_RPM /traffic_router.rpm
@@ -41,19 +41,19 @@ RUN curl -kvsL -o /jdk8.rpm -H 'Cookie: oraclelicense=accept-securebackup-cooki
rpm -ivh /jdk8.rpm && \
ln -sfv $(find /usr/java -mindepth 1 -maxdepth 1 -type d -name jdk\*) /opt/java
-# Install Tomcat and Tomcat Native
+# Install Tomcat and Tomcat Native
RUN cd / && rpm2cpio /traffic_router.rpm | cpio -ivd && \
- rpm2cpio /tomcat.rpm | cpio -ivd && \
+ rpm2cpio /tomcat.rpm | cpio -ivd && \
tar -C /opt -xvpf /opt/tomcat/bin/tomcat-native.tar.gz
# Compile and install Tomcat-native
RUN cd $(find /opt -maxdepth 1 -type d | grep tomcat-native )/native && \
./configure --prefix=/opt/tomcat --with-apr=`which apr-1-config` --with-java-home=/opt/java --with-ssl && \
make install
-
-ADD enroller/server_template.json \
- traffic_router/run.sh \
- traffic_ops/to-access.sh \
+
+ADD enroller/server_template.json \
+ traffic_router/run.sh \
+ traffic_ops/to-access.sh \
/
EXPOSE 53 80 3333