docs/sections/installation/install_from_source.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4
   5 ============================
   6 Installing from Source Code
   7 ============================
   8
   9 *Note: this document assumes UNIX Bash Shell.  Being Java, AAF works in Windows, but you will have to create your own script/instruction conversions.*
  10
  11 ------------------
  12 Modes
  13 ------------------
  14
  15 AAF can be run in various ways
  16   * Standalone (on your O/S)
  17   * Docker (localized)
  18   * Kubernetes
  19   * ONAP Styles
  20     * HEAT (Docker Container Based Initilization)
  21     * OOM  (a Helm Chart based Kubernetes Environment)
  22
  23 ------------------
  24 Prerequisites
  25 ------------------
  26
  27 You need the following tools to build and run AAF
  28   * git
  29   * maven
  30   * Java (JDK 1.8+, openjdk is fine)
  31   * Cassandra
  32      * a separate installation is fine
  33      * these instructions will start off with a Docker based Cassandra instance
  34   * Machine - one of the following
  35      * Standalone Java Processes - no additional running environments necessary
  36      * docker - typically available via packages for O/S
  37      * kubernetes - ditto
  38
  39
  40 ------------------
  41 Build from Source
  42 ------------------
  43 Choose the directory you wish to start in... This process will create an "authz" subdirectory::
  44
  45   $ mkdir -p ~/src
  46   $ cd ~/src
  47
  48 Use 'git' to 'clone' the master code::
  49
  50   $ git clone https://gerrit.onap.org/r/aaf/authz
  51
  52 Change to that directory::
  53
  54   $ cd authz
  55
  56 Use Maven to build::
  57
  58   << TODO, get ONAP Settings.xml>>
  59   $ mvn install
  60
  61 .. -----------------
  62 .. Standalone
  63 .. -----------------
  64
  65 -----------------
  66 Docker Mode
  67 -----------------
  68
  69 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.
  70
  71 From "authz"::
  72
  73   $ cd auth/auth-cass/src/main/cql
  74   $ vi config.dat
  75
  76 ===================
  77 Existing Cassandra
  78 ===================
  79
  80 AAF Casablanca has added a table.  If you have an existing AAF Cassandra, do the following::
  81
  82   ### If Container Cassandra, add these steps, otherwise, skip
  83   $ docker container cp init2_1.cql aaf_cass:/tmp
  84   $ docker exec -it aaf_cass bash
  85   (docker) $ cd /tmp
  86   ###
  87   $ cqlsh -f 'init2_1.cql'
  88
  89 =====================
  90 New Docker Cassandra
  91 =====================
  92
  93 Assuming you are in your src/authz directory::
  94
  95   $ cd auth/auth-cass/docker
  96   $ sh dinstall.sh
  97
  98 ---------------------
  99 AAF Itself
 100 ---------------------
 101
 102 Assuming you are in your src/authz directory::
 103
 104   $ cd auth/docker
 105   ### If you have not done so before (don't overwrite your work!)
 106   $ cp d.props.init d.props
 107
 108 You will need to edit and fill out the information in your d.props file.  Here is info to help
 109
 110 **Local Env info** - These are used to load the /etc/hosts file in the Containers, so AAF is available internally and externally
 111
 112   =============== =============
 113   Variable        Explanation
 114   =============== =============
 115   HOSTNAME        This must be the EXTERNAL FQDN of your host.  Must be in DNS or /etc/hosts
 116   HOST_IP         This must be the EXTERNAL IP of your host. Must be accessible from "anywhere"
 117   CASS_HOST       If Docker Cass, this is the INTERNAL FQDN/IP.  If external Cass, then DNS|/etc/hosts entry
 118   aaf_env         This shows up in GUI and certs, to differentiate environments
 119   aaf_register_as As pre-set, it is the same external hostname.
 120   cadi_latitude   Use "https://bing.com/maps", if needed, to locate your current Global Coords
 121   cadi_longitude  ditto
 122   =============== =============
 123
 124 ==============================
 125 "Bleeding Edge" Source install
 126 ==============================
 127
 128 AAF can be built, and local Docker Images built with the following::
 129
 130   $ sh dbuild.sh
 131
 132 Otherwise, just let it pull from Nexus
 133
 134 ==============================
 135 Configure AAF Volume
 136 ==============================
 137
 138 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.
 139
 140 This volume is created automatically, as necessary, and linked into the container when starting. ::
 141
 142   ## Be sure to have your 'd.props' file filled out before running.
 143   $ sh aaf.sh
 144
 145 ==============================
 146 Bootstrapping with Keystores
 147 ==============================
 148
 149 Start the container in bash mode, so it stays up. ::
 150
 151   $ bash aaf.sh bash
 152   id@77777:
 153
 154 In another shell, find out your Container name. ::
 155
 156   $ docker container ls | grep aaf_config
 157
 158 CD to directory with CA p12 files
 159
 160   * org.osaaf.aaf.p12
 161   * org.osaaf.aaf.signer.p12    (if using Certman to sign certificates)
 162
 163 Copy keystores for this AAF Env ::
 164
 165   $ docker container cp -L org.osaaf.aaf.p12 aaf_agent_<Your ID>:/opt/app/osaaf/local
 166   ### IF using local CA Signer
 167   $ docker container cp -L org.osaaf.aaf.signer.p12 aaf_agent_<Your ID>:/opt/app/osaaf/local
 168
 169 In Agent Window ::
 170
 171   id@77777: agent encrypt cadi_keystore_password
 172   ### IF using local CA Signer
 173   id@77777: agent encrypt cm_ca.local
 174
 175 Check to make sure all passwords are set ::
 176
 177   id@77777: grep "enc:" *.props
 178
 179 When good, exit from Container Shell and run AAF ::
 180
 181   id@77777: exit
 182   $ bash drun.sh
 183
 184 Check the Container logs for correct Keystore passwords, other issues ::
 185
 186   $ docker container logs aaf_<service>
 187
 188 Watch logs ::
 189
 190   $ sh aaf.sh taillog
 191
 192 Notes:
 193
 194 You can find an ONAP Root certificate, and pre-built trustores  for ONAP Test systems at:
 195   | authz/auth/sample/public/AAF_RootCA.cert
 196   | authz/auth/sample/public/truststoreONAPall.jks
 197
 198 Good Tests to run ::
 199
 200   ## From "docker" dir
 201   ##
 202   ## assumes you have DNS or /etc/hosts entry for aaf-onap-test.osaaf.org
 203   ##
 204   $ 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
 205   $ openssl s_client -connect aaf-onap-test.osaaf.org:8100
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219