From 15f3969cb88ce5576da368708dad1903828148f0 Mon Sep 17 00:00:00 2001 From: Instrumental Date: Fri, 20 Jul 2018 11:32:41 -0500 Subject: [PATCH] Document AAF Installation Issue-ID: AAF-292 Change-Id: Ic02bf086454dcd0de306f9e6d9c334fd0f6b21e7 Signed-off-by: Instrumental --- INFO.yaml | 6 +- auth/docker/Dockerfile.config | 1 + auth/docker/d.props.init | 12 +- auth/docker/dbounce.sh | 4 +- docs/sections/installation/install_from_source.rst | 218 +++++++++++++++++++++ .../installation/{fromsource.rst => sample.rst} | 0 6 files changed, 230 insertions(+), 11 deletions(-) create mode 100644 docs/sections/installation/install_from_source.rst rename docs/sections/installation/{fromsource.rst => sample.rst} (100%) diff --git a/INFO.yaml b/INFO.yaml index b90cb9b4..840eb5ec 100644 --- a/INFO.yaml +++ b/INFO.yaml @@ -3,9 +3,9 @@ project: 'aaf-authz' project_creation_date: '2017-07-12' lifecycle_state: 'Incubation' project_lead: &onap_releng_ptl - name: 'Ram Koya' - email: 'rk541m@att.com' - id: 'rampi_k' + name: 'Jonathan Gathman' + email: 'jonathan.gathman@us.att.com' + id: 'instrumental' company: 'ATT' timezone: 'America/Dallas' primary_contact: *onap_releng_ptl diff --git a/auth/docker/Dockerfile.config b/auth/docker/Dockerfile.config index f3bd6bc9..60e82ad1 100644 --- a/auth/docker/Dockerfile.config +++ b/auth/docker/Dockerfile.config @@ -11,6 +11,7 @@ COPY local /opt/app/aaf_config/local COPY public /opt/app/aaf_config/public COPY logs /opt/app/aaf_config/logs COPY bin/service.sh /opt/app/aaf_config/bin/agent.sh +COPY bin/aaf-cadi-aaf-${VERSION}-full.jar /opt/app/aaf_config/bin/ ENTRYPOINT ["/bin/bash","/opt/app/aaf_config/bin/agent.sh"] CMD [] diff --git a/auth/docker/d.props.init b/auth/docker/d.props.init index 8691591c..b0ba63d8 100644 --- a/auth/docker/d.props.init +++ b/auth/docker/d.props.init @@ -6,12 +6,12 @@ VERSION=2.1.2-SNAPSHOT CONF_ROOT_DIR=/opt/app/osaaf # Local Env info -HOSTNAME= +HOSTNAME=aaf.osaaf.org HOST_IP= -CASS_HOST=: +CASS_HOST=cass.aaf.osaaf.org: # AAF Machine info -aaf_env=DEV -aaf_register_as=$HOSTNAME -cadi_latitude= -cadi_longitude= +AAF_ENV=DEV +AAF_REGISTER_AS=$HOSTNAME +LATITUDE= +LONGITUDE= diff --git a/auth/docker/dbounce.sh b/auth/docker/dbounce.sh index e6367957..82aedd0c 100644 --- a/auth/docker/dbounce.sh +++ b/auth/docker/dbounce.sh @@ -1,4 +1,4 @@ #!/bin/bash -sh ./dstop.sh "$@" -sh ./dstart.sh "$@" +bash ./dstop.sh "$@" +bash ./dstart.sh "$@" diff --git a/docs/sections/installation/install_from_source.rst b/docs/sections/installation/install_from_source.rst new file mode 100644 index 00000000..4a4b03c5 --- /dev/null +++ b/docs/sections/installation/install_from_source.rst @@ -0,0 +1,218 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. + +Installing from Source Code +============================ + +*Note: this document assumes UNIX Bash Shell. Being AAF works in Windows, but you will have to create your own script/instruction conversions.* + +------------------ +Modes +------------------ + +AAF can be run in various ways + * Standalone (on your O/S) + * Docker (localized) + * Kubernetes + * ONAP Styles + * HEAT (Docker Container Based Initilization) + * OOM (a Helm Chart based Kubernetes Environment) + +------------------ +Prerequisites +------------------ + +You need the following tools to build and run AAF + * git + * maven + * Java (JDK 1.8+, openjdk is fine) + * Cassandra + * a separate installation is fine + * these instructions will start off with a Docker based Cassandra instance + * Machine - one of the following + * Standalone Java Processes - no additional running environments necessary + * docker - typically available via packages for O/S + * kubernetes - ditto + + +------------------ +Build from Source +------------------ +Choose the directory you wish to start in... This process will create an "authz" subdirectory:: + + $ mkdir -p ~/src + $ cd ~/src + +Use 'git' to 'clone' the master code:: + + $ git clone https://gerrit.onap.org/r/aaf/authz + +Change to that directory:: + + $ cd authz + +Use Maven to build:: + + << TODO, get ONAP Settings.xml>> + $ mvn install + +.. ----------------- +.. Standalone +.. ----------------- + +----------------- +Docker Mode +----------------- + +After you have successfully run maven, you will need a Cassandra. If you don't have one, here are instructions for a Docker Standalone Cassandra. For a *serious* endeavor, you need a multi-node Cassandra. + +From "authz":: + + $ cd auth/auth-cass/src/main/cql + $ vi config.dat + +=================== +Existing Cassandra +=================== + +AAF Casablanca has added a table. If you have an existing AAF Cassandra, do the following:: + + ### If Container Cassandra, add these steps, otherwise, skip + $ docker container cp init2_1.cql aaf_cass:/tmp + $ docker exec -it aaf_cass bash + (docker) $ cd /tmp + ### + $ cqlsh -f 'init2_1.cql' + +===================== +New Docker Cassandra +===================== + +Assuming you are in your src/authz directory:: + + $ cd auth/auth-cass/docker + $ sh dinstall.sh + +--------------------- +AAF Itself +--------------------- + +Assuming you are in your src/authz directory:: + + $ cd auth/docker + ### If you have not done so before (don't overwrite your work!) + $ cp d.props.init d.props + +You will need to edit and fill out the information in your d.props file. Here is info to help + +**Local Env info** - These are used to load the /etc/hosts file in the Containers, so AAF is available internally and externally + + =============== ============= + Variable Explanation + =============== ============= + HOSTNAME This must be the EXTERNAL FQDN of your host. Must be in DNS or /etc/hosts + HOST_IP This must be the EXTERNAL IP of your host. Must be accessible from "anywhere" + CASS_HOST If Docker Cass, this is the INTERNAL FQDN/IP. If external Cass, then DNS|/etc/hosts entry + aaf_env This shows up in GUI and certs, to differentiate environments + aaf_register_as As pre-set, it is the same external hostname. + cadi_latitude Use "https://bing.com/maps", if needed, to locate your current Global Coords + cadi_longitude ditto + =============== ============= + +============================== +"Bleeding Edge" Source install +============================== + +AAF can be built, and local Docker Images built with the following:: + + $ sh dbuild.sh + +Otherwise, just let it pull from Nexus + +============================== +Configure AAF Volume +============================== + +AAF uses a Persistent Volume to store data longer term, such as CADI configs, Organization info, etc, so that data is not lost when changing out a container. + +This volume is created automatically, as necessary, and linked into the container when starting. :: + + ## Be sure to have your 'd.props' file filled out before running. + $ sh aaf.sh + +============================== +Bootstrapping with Keystores +============================== + +Start the container in bash mode, so it stays up. :: + + $ bash aaf.sh bash + id@77777: + +In another shell, find out your Container name. :: + + $ docker container ls | grep aaf_config + +CD to directory with CA p12 files + + * org.osaaf.aaf.p12 + * org.osaaf.aaf.signer.p12 (if using Certman to sign certificates) + +Copy keystores for this AAF Env :: + + $ docker container cp -L org.osaaf.aaf.p12 aaf_agent_:/opt/app/osaaf/local + ### IF using local CA Signer + $ docker container cp -L org.osaaf.aaf.signer.p12 aaf_agent_:/opt/app/osaaf/local + +In Agent Window :: + + id@77777: agent encrypt cadi_keystore_password + ### IF using local CA Signer + id@77777: agent encrypt cm_ca.local + +Check to make sure all passwords are set :: + + id@77777: grep "enc:" *.props + +When good, exit from Container Shell and run AAF :: + + id@77777: exit + $ bash drun.sh + +Check the Container logs for correct Keystore passwords, other issues :: + + $ docker container logs aaf_ + +Watch logs :: + + $ sh aaf.sh taillog + +Notes: + +You can find an ONAP Root certificate, and pre-built trustores for ONAP Test systems at: + | authz/auth/sample/public/AAF_RootCA.cert + | authz/auth/sample/public/truststoreONAPall.jks + +Good Tests to run :: + + ## From "docker" dir + ## + ## assumes you have DNS or /etc/hosts entry for aaf-onap-test.osaaf.org + ## + $ curl --cacert ../sample/public/AAF_RootCA.cer -u demo@people.osaaf.org:demo123456! https://aaf-onap-test.osaaf.org:8100/authz/perms/user/demo@people.osaaf.org + $ openssl s_client -connect aaf-onap-test.osaaf.org:8100 + + + + + + + + + + + + + + diff --git a/docs/sections/installation/fromsource.rst b/docs/sections/installation/sample.rst similarity index 100% rename from docs/sections/installation/fromsource.rst rename to docs/sections/installation/sample.rst -- 2.16.6