Developer Quick Start Guide
***************************

The following is a brief guide on how to deploy a SAS App Engine and prepare it
for developing and testing App Engine components in-place.

Installation
============

First, obtain the Installable ISO media.
The weekly developer build can be downloaded from the following location:
https://sas-app-engine-ci.s3.amazonaws.com/appengine-8-devel-x86_64.iso

Next, create a virtual machine in which to install the App Engine.
The following minimum requirements are recommended:

* 64-bit CPU
* 2 GB RAM minimum, 4 GB recommended
* 100 GB disk space
* Internet connection

Attach the ISO to the virtual machine and proceed with installation.
By default, half of the available disk space will be reserved for image
building. If you customize the partitioning scheme you must leave unallocated
LVM space for image builds.

**Note:** Do not enable disk encryption.

System Configuration
====================

After the install, you must modify a number of system configuration files.
Log into the console with username ``root`` and the password chosen at install
time.

**/etc/sysconfig/network** : App Engine requires a valid hostname other than
"localhost". If one has not been assigned by DHCP, set it here. The hostname
*must* be resolveable, so if it is not then add it to **/etc/hosts** as well.
If the hostname was changed, reboot or set it manually with the ``hostname``
command.

**/etc/ssh/sshd_config** : The ``amiconfig`` daemon disables password SSH logins
by default when used with certain virtualization platforms.

* Look for a line containing ``PasswordAuthentication no`` and delete it, if it
  exists.
* Run ``chkconfig amiconfig off`` to prevent amiconfig from modifying the
  configuration in the future.
* Run ``service sshd restart`` so the changes take effect.

At this point you may wish to switch to using SSH for convenience rather than
direct console access.

**/root/.conaryrc** : Create this file containing the following line::

    includeConfigFile https://updates.sas.com/conaryrc

This will ensure that system updates can find the App Engine upstream
repositories.

**/etc/conary/system-model** : In this file, change ``group-rbuilder-appliance`` to
``group-rbuilder-devel``. Save your changes, then run ``conary updateall``.
This will both bring the App Engine to the latest build if the ISO is out of
date, and also install all of the developer tools and libraries that are not in
the ISO.

App Engine Configuration
========================

Edit **/etc/rbuilder.pp**. Set ``$admin_email``. Set project_domain to
something unique to your App Engine install, for example "bobs-appengine".
Repository hostnames for newly created projects will be constructed from this
value. project_domain does not need to be resolveable. Namespace and
project_domain can be changed later, but will not affect existing projects.

Run ``puppet apply --debug /etc/rbuilder.pp``. This will adjust additional
system configuration, create the App Engine configuration, and start services.

Run ``/usr/share/rbuilder/scripts/mint-admin user-add`` to create your
App Engine user account.

**Note:** Do not name the App Engine account "admin".

Using ``useradd``, create a non-root system user account for development
purposes. It does not have to have the same name as the App Engine user created
above.

Developer Setup
===============

This section details how to check out the App Engine source code, build it, and
reconfigure the running App Engine run out of the checkout instead of the
installed packages. It is not necessary to perform this step immediately; you
can come back to it after verifying initial operation of the App Engine
installation if you wish.

First, as root, create a directory in which to place the checkout. ::

    mkdir /srv/code
    chown myuser:myuser /srv/code

Then, as the non-root user, checkout the App Engine codebase from Github. ::

    sudo -u myuser -i
    cd /srv/code
    git clone https://github.com/sassoftware/appengine -b master
    ./appengine/multigit
    make -C appengine

Finally, as root, insert the newly-built checkout into the Python search path::

    make -C /srv/code/appengine install-pth

Reboot the App Engine to complete the initial setup.

rbuild Configuration
====================

**rbuild** is the primary command-line tool for interacting with an App Engine.

Switch to the development user by logging out and back in or using ``sudo -u
myuser -i``. Run ``rbuild config --ask``. You can accept the defaults when
present.

Run ``rbuild config --conaryrc --rmakerc`` to finish preparing the rbuild environment.

Example Project
===============

The following will create an example project with a CentOS minimal install and
some extra packages and build an image.

Create a project and branch to work in. Run ``rbuild create project`` and
give the following answers::

    Project name:           Example Project
    Project description:
    Unique name:            example
    Domain name:

Create a branch of the project using ``rbuild create branch``::

    Project name:           example
    Branch name:            1
    Branch description:
    Namespace:
    Platform:               1 (or whichever number corresponds to CentOS 6)

Now initialize the checkout with ``rbuild init example 1`` and ``cd
example-1/Development``.

Next create "image definitions", which describe which kind of images this
project will build. Run ``rbuild add imagedef vmwareImage x86_64`` to add a
VMware Workstation image output. For "Image name" give "vmware64", and leave
the rest of the answers at their defaults. To see what other image types are
available, see ``rbuild list imagetypes``.

Create a "group recipe" to describe which components will go into the image.
Run ``rbuild checkout group-example-appliance``, then edit
``group-example-appliance/group-example-appliance.recipe``. Set the "version"
variable to a non-empty string (e.g. "1"). Change "pass" at the end to the following::

    r.add("rsync")
    r.add("vim-enhanced")

Save and close the recipe, then run ``rbuild build groups`` and finally
``rbuild build images``. At the end of the image build, rbuild will print a url
which you can download to get your VMware image.