Installing a Development Environment
====================================
This guide gives a step by step installation instructions that are simpler
then what the s2aio.sh script does (e.g. it does not involve a docker registry
installation and configuration).

The below steps must be executed using a passwordless sudoer user.

Install Swift and Keystone using devstack
-----------------------------------------

Clone devstack:

::

    git clone git://github.com/openstack-dev/devstack.git

Create a localrc file under the devstack repository root directory:

::

    ENABLE_HTTPD_MOD_WSGI_SERVICES=False
    KEYSTONE_IP=127.0.0.1
    SWIFT_IP=127.0.0.1
    ENABLED_SERVICES=key,swift,mysql
    ADMIN_USER=admin
    ADMIN_PASSWORD=$ADMIN_USER
    ADMIN_PROJECT=ADMIN_USER
    DATABASE_PASSWORD=admin
    RABBIT_PASSWORD=$ADMIN_PASSWORD
    SERVICE_PASSWORD=$ADMIN_PASSWORD

    OS_IDENTITY_API_VERSION=2
    OS_AUTH_URL="http://$KEYSTONE_IP:5000/v3"
    OS_USERNAME=$ADMIN_USER
    OS_USER_DOMAIN_ID=default
    OS_PASSWORD=$ADMIN_PASSWORD
    OS_PROJECT_NAME=$ADMIN_USER
    OS_PROJECT_DOMAIN_ID=default
    OS_REGION_NAME=RegionOne

    SERVICE_HOST=$SWIFT_IP
    SWIFT_SERVICE_PROTOCOL=http
    SWIFT_DEFAULT_BIND_PORT=8080
    SWIFT_SERVICE_LOCAL_HOST=$SERVICE_HOST
    SWIFT_SERVICE_LISTEN_ADDRESS=$SERVICE_HOST
    # Use minimum 2GB for running the storlets tests
    SWIFT_LOOPBACK_DISK_SIZE=20G
    SWIFT_HASH=1234567890

Run the stack.sh script.
Before proceeding, we need to stop the
swift instances that were executed by the
stack.sh. From the same directory do:

::
    source functions
    source lib/swift
    stop_swift

Finally, add the swift devices to fstab:

::

    sudo sh -c 'echo "/opt/stack/data/swift/drives/images/swift.img /opt/stack/data/swift/drives/sdb1 xfs loop" >> /etc/fstab'

Configure a user and project in Keystone
----------------------------------------

We use the opnstack cli to configure a user and project
used by the storlets functional tests. We start by
defining some environment variables:

::

    export OS_IDENTITY_API_VERSION=2
    export OS_AUTH_URL="http://$KEYSTONE_IP:5000/v3"
    export OS_USERNAME=$ADMIN_USER
    export OS_USER_DOMAIN_ID=default
    export OS_PASSWORD=$ADMIN_PASSWORD
    export OS_PROJECT_NAME=$ADMIN_USER
    export OS_PROJECT_DOMAIN_ID=default
    export OS_REGION_NAME=RegionOne

We now create the project and user:

::

    openstack project create test
    openstack user create --project test --password testing tester
    openstack role add --user tester --project test admin

We now test that the setup by having the user 'tester' to stat the account 'test'. We use the Swift client cli.
A convenient way to do so is to edit the user's .bashrc adding the lines:

::

    export OS_USERNAME=tester
    export OS_PASSWORD=testing
    export OS_TENANT_NAME=test
    export OS_AUTH_URL=http://127.0.0.1:5000/v3

Now do:

::

    source .bashrc
    swift stat

Install Storlets
================

Install Dependencies
--------------------
We need the following for the Java parts

::

    sudo add-apt-repository -y ppa:openjdk-r/ppa
    sudo apt-get update
    sudo apt-get install -y openjdk-8-jdk
    sudo apt-get install -y ant

We need the following for Docker

::

    sudo apt-get -y install docker.io
    ln -sf /usr/bin/docker.io /usr/local/bin/docker
    sed -i '$acomplete -F _docker docker' /etc/bash_completion.d/docker
    update-rc.d docker defaults

Get and install the storlets code
---------------------------------

::

    cd $HOME
    git clone https://github.com/openstack/storlets.git
    cd storlets
    sudo ./install_libs.sh
    sudo python setup.py install
    tar czf /tmp/storlets.tar.gz .
    cd -

.. note:: You don't need sudo for 'python setup.py install' when installing the storlets package into your python virtualenv.

Build the Docker image to be used for running storlets
------------------------------------------------------
Step 1: Create a working space for building the docker images, e.g.

::

    mkdir -p $HOME/docker_repos
    sudo docker pull ubuntu:14_04

Step 2: Create a Docker image with Java

::

    mkdir -p $HOME/docker_repos/ubuntu_14.04_jre8
    cd $HOME/docker_repos/ubuntu_14.04_jre8
    cp $HOME/storlets/src/java/dependencies/logback-classic-1.1.2.jar .
    cp $HOME/storlets/src/java/dependencies/logback-core-1.1.2.jar .
    cp $HOME/storlets/src/java/dependencies/slf4j-api-1.7.7.jar .
    cp $HOME/storlets/src/java/dependencies/json_simple-1.1.jar .
    cp $HOME/storlets/src/java/dependencies/logback.xml .
    cd -

Create the file: $HOME/docker_repos/ubuntu_14.04_jre8/Dockerfile
with the following content:

::

    FROM ubuntu:14.04
    MAINTAINER root

    # The following operations shoud be defined in one line
    # to prevent docker images from including apt cache file.
    RUN apt-get update && \
    apt-get install python -y && \
    apt-get install software-properties-common -y && \
    add-apt-repository ppa:openjdk-r/ppa -y && \
    apt-get update && \
    apt-get install openjdk-8-jre -y && \
    apt-get clean

    COPY logback-classic-1.1.2.jar  /opt/storlets/
    RUN ["chmod", "0744", "/opt/storlets/logback-classic-1.1.2.jar"]

    COPY logback-core-1.1.2.jar /opt/storlets/
    RUN ["chmod", "0744", "/opt/storlets/logback-core-1.1.2.jar"]

    COPY logback.xml    /opt/storlets/
    RUN ["chmod", "0744", "/opt/storlets/logback.xml"]

    COPY slf4j-api-1.7.7.jar    /opt/storlets/
    RUN ["chmod", "0744", "/opt/storlets/slf4j-api-1.7.7.jar"]

    COPY json_simple-1.1.jar    /opt/storlets/
    RUN ["chmod", "0744", "/opt/storlets/json_simple-1.1.jar"]

Build the image

::

    cd $HOME/docker_repos/ubuntu_14.04_jre8
    sudo docker build -q -t ubuntu_14.04_jre8 .
    cd -


Step 3: Augment the above created image with the storlets stuff

::

    mkdir -p $HOME/docker_repos/ubuntu_14.04_jre8_storlets
    cd $HOME/docker_repos/ubuntu_14.04_jre8_storlets
    cp $HOME/storlets/src/java/SBus/bin/libjsbus.so .
    cp $HOME/storlets/src/java/SBus/bin/SBusJavaFacade.jar .
    cp $HOME/storlets/src/java/SDaemon/bin/SDaemon.jar .
    cp $HOME/storlets/src/java/SCommon/bin/SCommon.jar .
    cp $HOME/storlets/src/c/sbus/libsbus.so .
    cp $HOME/storlets/install/storlets/roles/docker_storlet_engine_image/files/init_container.sh .
    cp $HOME/storlets/install/storlets/roles/docker_storlet_engine_image/files/logback.xml .
    wget https://bootstrap.pypa.io/get-pip.py
    cp /tmp/storlets.tar.gz .
    tar -xvf storlets.tar.gz
    cd -

Create the file: $HOME/docker_repos/ubuntu_14.04_jre8_storlets/Dockerfile
with the following content:

::

    FROM ubuntu_14.04_jre8

    MAINTAINER root

    RUN [ "groupadd", "-g", "1003", "swift" ]
    RUN [ "useradd", "-u" , "1003", "-g", "1003", "swift" ]

    # Copy files
    COPY ["logback.xml", "init_container.sh", "/opt/storlets/"]

    RUN ["chmod", "0744", "/opt/storlets/logback.xml"]
    RUN ["chmod", "0755", "/opt/storlets/init_container.sh"]

    # Install c java resources
    COPY ["libsbus.so", "/usr/local/lib/storlets/"]

    # Install storlets java resources
    COPY ["SBusJavaFacade.jar", "libjsbus.so", "SDaemon.jar", "SCommon.jar", "/opt/storlets/"]

    # Install pip
    COPY ["get-pip.py", "/opt/storlets"]
    RUN ["python",  "/opt/storlets/get-pip.py"]
    ENV PYTHONWARNINGS="ignore:a true SSLContext object"

    # Install python codes
    COPY ["storlets", "/opt/storlets/"]
    RUN cd /opt/storlets/ && \
        pip install -r requirements.txt && \
        python setup.py install

    CMD ["prod", "/mnt/channels/factory_pipe", "DEBUG"]

    ENTRYPOINT ["/opt/storlets/init_container.sh"]

Build the image

::

    cd $HOME/docker_repos/ubuntu_14.04_jre8_storlets
    sudo docker build -q -t ubuntu_14.04_jre8_storlets .
    cd -

Step 4: Create a tenant specific image. The engine looks for images
having the name <tenand id>.
First, we get the tenant id. Using the Swift cli and the above create user do:

::

    swift --os-auth-url http://127.0.0.1:5000/v3 --os-project-name test --os-project-domain-name default --os-username tester --os-password testing stat

The response from the above contains the account line, e.g.:

::

    Account: AUTH_719caee804974c14a8632a760a7f85f7

The account id is the number following the 'AUTH\_' prefix.

Next create the file $HOME/docker_repos/ubuntu_14.04_jre8_storlets_<account id>/Dockerfile
with the following content:

::

    FROM ubuntu_14.04_jre8_storlets

    MAINTAINER root

    RUN apt-get install vim

Build the image

::

    cd $HOME/docker_repos/ubuntu_14.04_jre8_storlets_<account id>
    sudo docker build -q -t <account id> .
    cd -

Create the storlets run time environment
----------------------------------------
Create the run time directory

::

    export STORLETS_HOME=/home/docker_device
    sudo mkdir -p $STORLETS_HOME
    sudo chmod 777 $STORLETS_HOME

Create the scripts directory and populate it.
Note that these scripts are executed by the middleware but
require root privileges.

::

    mkdir $STORLETS_HOME/scripts
    cd STORLETS_HOME/scripts
    cp $HOME/scripts/restart_docker_container .
    sudo chown root:root restart_docker_container
    sudo chmod 04755 restart_docker_container
    cp $HOME/scripts/send_halt_cmd_to_daemon_factory.py .
    sudo chown root:root send_halt_cmd_to_daemon_factory.py
    sudo chmod 04755 send_halt_cmd_to_daemon_factory.py

The run time directory will be later populated by the middleware with:
 #. storlets - Docker container mapped directories keeping storlet jars
 #. pipe - A Docker container mapped directories holding named pipes shared between the middleware and the containers.
 #. logs - the logs of storlets running inside the docker containers
 #. cache - a local cache for storlet jars

Configure Swift to work with the middleware components
------------------------------------------------------
Step 1: Edit the proxy server config file /etc/swift/proxy-server.conf and
do the following:

 #. Add the storlet_handler to the proxy server pipline just before the slo middleware as shown below:

 ::

    pipeline = catch_errors gatekeeper healthcheck proxy-logging cache container_sync bulk tempurl ratelimit authtoken keystoneauth container-quotas account-quotas storlet_handler slo dlo versioned_writes proxy-logging proxy-server

 #. At the bottom of the file add the following configuration block:

 ::

    [filter:storlet_handler]
    use = egg:storlets#storlet_handler
    storlet_container = storlet
    storlet_dependency = dependency
    storlet_gateway_module = docker
    storlet_gateway_conf = /etc/swift/storlet_docker_gateway.conf
    storlet_execute_on_proxy_only = false
    execution_server = proxy

Step 2: Edit the object server(s) config file(s).
In a SAIO environment these would be:
/etc/swift/object-server/1.conf through /etc/swift/object-server/4.conf
otherwise the file is typically /etc/swift/object-server.conf

 1. Add the storlet_handler to the object server pipline just before the slo object-server as shown below:

 ::

    pipeline = recon storlet_handler object-server

 2. At the bottom of the file add the following configuration block:

 ::

    [filter:storlet_handler]
    use = egg:storlets#storlet_handler
    storlet_container = storlet
    storlet_dependency = dependency
    storlet_gateway_module = docker
    storlet_gateway_conf = /etc/swift/storlet_docker_gateway.conf
    storlet_execute_on_proxy_only = false
    execution_server = object

Step 3: Add the Docker gateway configuration file.
Under /etc/swift create a file named storlet_docker_gateway.conf
with the following content:

::

    [DEFAULT]
    storlet_logcontainer = storletlog
    lxc_root = /home/docker_device/scopes
    cache_dir = /home/docker_device/cache/scopes
    log_dir = /home/docker_device/logs/scopes
    script_dir = /home/docker_device/scripts
    storlets_dir = /home/docker_device/storlets/scopes
    pipes_dir = /home/docker_device/pipes/scopes
    storlet_timeout = 40
    docker_repo =
    restart_linux_container_timeout = 3

Step 4:
Create and edit the file /etc/swift/storlet-proxy-server.conf:

::

    cp /etc/swift/proxy-server.conf /etc/swift/storlet-proxy-server.conf

Change the pipeline in /etc/swift/storlet-proxy-server.conf to be:

::

    pipeline = proxy-logging cache slo proxy-logging proxy-server

Step 5: restart swift

::

    sudo swift-init all restart

Enable the account for storlets
-------------------------------
We use the same test account and tester user created above.
To enable the account for storlets we need to set an appropriate
user metadata on the account and create within the account the
various Swift containers assumed by the engine.

We use the swift cli as follows:

::

  swift post \
  --os-auth-url=http://127.0.0.1:5000/v3 \
  --os-username=tester \
  --os-password=testing \
  --os-project-name=test \
  --os-project-domain-name default \
  --meta "Storlet-Enabled:True"


  swift post \
  --os-auth-url=http://127.0.0.1:5000/v3 \
  --os-username=tester \
  --os-password=testing \
  --os-project-name=test \
  --os-project-domain-name default \
  storlet

  swift post \
  --os-auth-url=http://127.0.0.1:5000/v3 \
  --os-username=tester \
  --os-password=testing \
  --os-project-name=test \
  --os-project-domain-name default \
  dependency

  swift post \
  --os-auth-url=http://127.0.0.1:5000/v3 \
  --os-username=tester \
  --os-password=testing \
  --os-project-name=test \
  --os-project-domain-name default \
  storletlog

Run the functional tests
------------------------
The functional tests upload various storlets and execute them.
Running the functional tests successfully proves the installation
completed successfully.

The functional tests are designed to run over a clustered installation
(that is not an all in one install). Hence, running the tests require
a cluster connfiguration file.

Step 1: Create the file $HOME/storlets/cluster_config.json with the below
content.

::

    {
        "all" : {
            "docker_device": "/home/docker_device",
            "storlet_source_dir": "~/storlets",
            "keystone_public_url": "http://127.0.0.1:5000/v3",
            "swift_endpoint_host": "127.0.0.1",
            "swift_public_url": "http://127.0.0.1:8080/v1",
            "storlets_enabled_attribute_name": "storlet-enabled",
            "storlets_default_project_name": "test",
            "storlets_default_project_user_name": "tester",
            "storlets_default_project_user_password": "testing",
            "storlets_default_project_member_user": "tester_member",
            "storlets_default_project_member_password": "member",
        }
    }

Step 2: Run the functional tests

::

    cd $HOME/storlets
    ./.functests dev