You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by mi...@apache.org on 2018/10/10 18:26:21 UTC
[trafficcontrol] 23/39: Added missing commands/correcting existing
commands for `admin.pl` docs
This is an automated email from the ASF dual-hosted git repository.
mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
commit 305dc1dfd3bea862410bfd8df2389fd6aac82df3
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Thu Sep 27 06:57:56 2018 -0600
Added missing commands/correcting existing commands for `admin.pl` docs
Also updated formatting - lists of key/value pairs -> actual key/value pairs, implicitly numbered lists etc.
---
docs/source/development/traffic_ops.rst | 212 +++++++++++++++++---------------
1 file changed, 114 insertions(+), 98 deletions(-)
diff --git a/docs/source/development/traffic_ops.rst b/docs/source/development/traffic_ops.rst
index 12a21c1..117c14c 100644
--- a/docs/source/development/traffic_ops.rst
+++ b/docs/source/development/traffic_ops.rst
@@ -106,13 +106,22 @@ traffic_ops/ - The root of the Traffic Ops project
- ats_config/ - an attempt to provide an easier method of obtaining and/or writing configuration files for Apache Trafficserver cache servers
- auth/ - a simple authentication server that mimics the authentication process of Traffic Ops, and provides a detailed view of a logged-in user's permissions and capabilities
- goto/ - an Angular (1.x) web page backed by a Go server that provides a ReST API interface for mySQL servers
- - postgrest/ - originally probably going to be a web server that provides a ReST API for postgreSQL servers, this only contains a simple - albiet unfinished - Docker container specification for running postgreSQL client tools and/or server(s)
+ - postgrest/ - originally probably going to be a web server that provides a ReST API for postgreSQL servers, this only contains a simple - albeit unfinished - Docker container specification for running postgreSQL client tools and/or server(s)
- server/ - a living copy of the original attempt at re-writing Traffic Ops in Go
- traffic_ops_auth/ - proof-of-concept for authenticating, creating and deleting users in a Traffic Ops schema.
- url-rewriter-nginx/ - Docker container specification for a modification to the NginX web server, meant to make it suitable for use as a caching server at the Edge-tier or Mid-tier levels of the Traffic Control architecture
- webfront/ - a simple HTTP caching server written from the ground-up, meant to be suitable as a caching server at the Edge-tier or Mid-tier levels of the Traffic Control architecture
- - install/
+ - install/ - contains all of the resources necessary for a full install of Traffic Ops
+
+ - bin/ - binaries related to installing Traffic Ops, as well as installing its prerequisites, certificates, and database
+ - data/ - almost nothing
+ - etc/ - this directory left empty; it's used to contain post-installation extensions and resources
+ - lib/ - contains libraries used by the various installation binaries
+
+ - testing/ - holds utilities for testing the Traffic Ops API, as well as comparing two separate API instances (for e.g. comparing a new build to a known-to-work build)
+ - traffic_ops_golang/ - has all of the functionality that has been re-written from Perl into Go
+ - vendor/ - contains "vendored" packages from third party sources
Perl Formatting Conventions
===========================
@@ -144,137 +153,144 @@ Perl Formatting Conventions
Database Management
===================
-.. Add db naming conventions
-
-The admin.pl script is for use in managing the Traffic Ops database tables. Below is an example of its usage.
-
-``$ db/admin.pl``
-
-Usage: db/admin.pl [--env (development|test|production)] [arguments]
-
-Example: ``db/admin.pl --env=test reset``
-
-Purpose: This script is used to manage the database. The environments are defined in the dbconf.yml, as well as the database names.
-
-- To use the ``admin.pl`` script, you may need to add ``traffic_ops/lib`` and ``traffic_ops/local/lib/perl5`` to your `PERL5LIB <http://modperlbook.org/html/3-9-2-2-Using-the-PERL5LIB-environment-variable.html>`_ environment variable.
-
-+-----------+--------------------------------------------------------------------+
-| Arguments | Description |
-+===========+====================================================================+
-| create | Execute db 'create' the database for the current environment. |
-+-----------+--------------------------------------------------------------------+
-| down | Roll back a single migration from the current version. |
-+-----------+--------------------------------------------------------------------+
-| drop | Execute db 'drop' on the database for the current environment. |
-+-----------+--------------------------------------------------------------------+
-| redo | Roll back the most recently applied migration, then run it again. |
-+-----------+--------------------------------------------------------------------+
-| reset | Execute db drop, create, load_schema, migrate on the database for |
-| | the current environment. |
-+-----------+--------------------------------------------------------------------+
-| seed | Execute SQL from db/seeds.sql for loading static data. |
-+-----------+--------------------------------------------------------------------+
-| setup | Execute db drop, create, load_schema, migrate, seed on the |
-| | database for the current environment. |
-+-----------+--------------------------------------------------------------------+
-| status | Print the status of all migrations. |
-+-----------+--------------------------------------------------------------------+
-| upgrade | Execute migrate then seed on the database for the current |
-| | environment. |
-+-----------+--------------------------------------------------------------------+
+The ``app/db/admin.pl`` script is for use in managing the Traffic Ops database tables. This essentially serves as a front-end for `Goose <https://bitbucket.org/liamstask/goose/>`_ Below is an example of its usage.
+
+.. note:: For proper resolution of Perl library paths and SOL statement files, it's recommended that this script be run from the ``app`` directory
+
+``db/admin.pl [options] command``
+
+Options:
+
+--env An environment specification. One of ``development``, ``integration``, ``production``, or ``test``. Default is ``development``.
+
+.. note:: The ``$MOJO_MODE`` environment variable is set to the value of the environment
+
+Commands:
+
+createdb
+ Creates the database for the current environment
+create_user
+ Creates the user defined for the current environment
+dbversion
+ Displays the database version that results from the current sequence of migrations
+down
+ Rolls back a single migration from the current version
+drop
+ Drops the database for the current environment
+drop_user
+ Drops the user defined for the current environment
+load_schema
+ Sets up the database for the current environment according to the SQL statements in ``app/db/create_tables.sql``
+migrate
+ Runs a migration on the database for the current environment
+patch
+ Patches the database for the current environment using the SQL statements from the ``app/db/patches.sql``
+redo
+ Rolls back the most recently applied migration, then run it again
+reset
+ Creates the user defined for the current environment, drops the database for the current environment, creates a new one, loads the schema into it, and runs a single migration on it
+reverse_schema
+ Reverse engineers the ``app/lib/Schema/Result/*`` files from the environment database
+seed
+ Executes the SQL statements from the ``app/db/seeds.sql`` file for loading static data
+show_users
+ Displays a list of all users registered with the PostgreSQL server
+status
+ Prints the status of all migrations
+upgrade
+ Performs a migration on the database for the current environment, then seeds it and patches it using the SQL statements from the ``app/db/patches.sql`` file
+
+.. code-block::bash
+ :caption: Example Usage
+
+ db/admin.pl --env=test reset
+
+The environments are defined in the ``app/db/dbconf.yml`` file, and the name of the database generated will be the name of the environment for which it was created. To use the ``admin.pl`` script, you may need to add ``traffic_ops/lib`` and ``traffic_ops/local/lib/perl5`` to your `PERL5LIB <http://modperlbook.org/html/3-9-2-2-Using-the-PERL5LIB-environment-variable.html>`_ environment variable.
+
+
Installing The Developer Environment
====================================
To install the Traffic Ops Developer environment:
-1. Clone the trafficcontrol repository from `github.com <https://github.com/apache/trafficcontrol>`_.
-2. Install the local dependencies using Carton (cpanfile).
-
- ::
-
- $ cd traffic_ops/app
- $ carton
-
-3. Set up a role (user) in Postgres
-
- See Postgres instructions on initdb https://wiki.postgresql.org/wiki/First_steps
-
+#. Clone the `Traffic Control repository <https://github.com/apache/trafficcontrol>`_ from GitHub.
+#. Install the local dependencies using `Carton <https://metacpan.org/release/Carton>`_.
-4. Enter ``db/admin.pl --env=<enviroment name> setup`` to set up the traffic_ops database(s).
+ .. code-block::shell
+ :caption: Install Development Dependencies
- - Unit test database: ``$ db/admin.pl --env=test setup``
- - Development database: ``$ db/admin.pl --env=development setup``
- - Integration database: ``$ db/admin.pl --env=integration setup``
+ cd traffic_ops/app
+ carton
- |
+#. Set up a role (user) in PostgreSQL
- Running the the admin.pl script in setup mode should look like this: ::
+ .. seealso:: `PostgreSQL instructions on setting up a database <https://wiki.postgresql.org/wiki/First_steps>`_.
- master $ db/admin.pl --env=development setup
- Using database.conf: conf/development/database.conf
- Using database.conf: conf/development/database.conf
- Using database.conf: conf/development/database.conf
- Using database.conf: conf/development/database.conf
- Using database.conf: conf/development/database.conf
- Using database.conf: conf/development/database.conf
- Executing 'drop database to_development'
- Executing 'create database to_development'
- Creating database tables...
- Warning: Using a password on the command line interface can be insecure.
- Migrating database...
- goose: migrating db environment 'development', current version: 0, target: 20150210100000
- OK 20141222103718_extension.sql
- OK 20150108100000_add_job_deliveryservice.sql
- OK 20150205100000_cg_location.sql
- OK 20150209100000_cran_to_asn.sql
- OK 20150210100000_ds_keyinfo.sql
- Seeding database...
- Warning: Using a password on the command line interface can be insecure.
-5. (Optional) To load temporary data into the tables: ``$ perl bin/db/setup_kabletown.pl``
+#. Use the ``setup`` command of the ``admin.pl`` script (see `Database Management`_ for usage) to set up the traffic_ops database(s).
-6. Run the postinstall script: ``traffic_ops/install/bin/postinstall``
+ Example Output::
-7. To start Traffic Ops, enter ``$ bin/start.pl``
+ $ db/admin.pl --env=development setup
+ Using database.conf: conf/development/database.conf
+ Using database.conf: conf/development/database.conf
+ Using database.conf: conf/development/database.conf
+ Using database.conf: conf/development/database.conf
+ Using database.conf: conf/development/database.conf
+ Using database.conf: conf/development/database.conf
+ Executing 'drop database to_development'
+ Executing 'create database to_development'
+ Creating database tables...
+ Warning: Using a password on the command line interface can be insecure.
+ Migrating database...
+ goose: migrating db environment 'development', current version: 0, target: 20150210100000
+ OK 20141222103718_extension.sql
+ OK 20150108100000_add_job_deliveryservice.sql
+ OK 20150205100000_cg_location.sql
+ OK 20150209100000_cran_to_asn.sql
+ OK 20150210100000_ds_keyinfo.sql
+ Seeding database...
+ Warning: Using a password on the command line interface can be insecure.
- The local Traffic Ops instance uses an open source framework called morbo, starting following the start command execution.
+#. (Optional) To load the 'KableTown' example/testing data set into the tables, use the ``setup_kabletown.pl`` script located in ``app/bin/db/``.
- Start up success includes the following:
+ .. note:: To ensure proper paths to Perl libraries and resource files, the ``setup_kabletown.pl`` should be run from within the ``app/`` directory.
- ::
+#. Run the ``postinstall`` script, located in ``install/bin/``
+#. To start Traffic Ops, use the ``start.pl`` script located in the ``app/bin`` directory. If the server starts successfully, the STDOUT of the process should contain the line ``[<date and time>] [INFO] Listening at "http://*:3000"``, followed by the line ``Server available at http://127.0.0.1:3000`` (using default settings for port number and listening address, and where ``<date and time>`` is an actual date and time in ISO format).
- [2015-02-24 10:44:34,991] [INFO] Listening at "http://*:3000".
+ .. note:: To ensure proper paths to Perl libraries and resource files, the ``start.pl`` script should be run from within the ``app/`` directory.
- Server available at http://127.0.0.1:3000.
+#. Using a web browser, navigate to the given address: ``http://127.0.0.1:3000``
+#. A prompt for login credentials should appear. Assuming default settings are used, the initial login credentials will be
-8. Using a browser, navigate to the given address: ``http://127.0.0.1:3000``
-9. For the initial log in:
+ :User name: ``admin``
+ :Password: ``password``
- - User name: admin
- - Password: password
+#. Change the login credentials.
-10. Change the log in information.
+ .. seealso:: :ref:`to-using`
Test Cases
==========
Use prove to execute test cases. Execute after a carton install:
- To run the Unit Tests: ``$ local/bin/prove -qrp t/``
-* To run the Integration Tests: ``$ local/bin/prove -qrp t_integration/``
+- To run the Integration Tests: ``$ local/bin/prove -qrp t_integration/``
The KableTown CDN example
-------------------------
The integration tests will load an example CDN with most of the features of Traffic Control being used. This is mostly for testing purposes, but can also be used as an example of how to configure certain features. To load the KableTown CDN example and access it:
-1. Run the integration tests
-2. Start morbo against the integration database: ``export MOJO_MODE=integration; ./bin/start.pl``
-3. Using a browser, navigate to the given address: ``http://127.0.0.1:3000``
-4. For the initial log in:
+#. Run the integration tests
+#. Start morbo against the integration database: ``export MOJO_MODE=integration; ./bin/start.pl``
+#. Using a browser, navigate to the given address: ``http://127.0.0.1:3000``
+#. For the initial log in:
- - User name: admin
- - Password: password
+ :User name: ``admin``
+ :Password: ``password``
Extensions