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