p4ws - Perforce Web Services
----------------------------

## Project Structure

Perforce Web Services is actually a suite of several different kinds of
applications, client libraries, and utilities (like installers) that form
a kind of microservice system for applications.

Projects that are simple (they make one thing), have all their code directly
underneath this directory.

Projects that have clients, or are broken up into multiple related projects,
have a subdirectory under this that groups these related projects together.
See the p4_project_services tree as an example.


## Project Naming

Because these projects may be distributed via RubyGems for heavily customized
deployments, prefix everything with 'p4_'.


## Versioning

Each project is versioned independently.

The underlying p4_web_api is actually quite tied to the underlying P4 server
version, since that's what defines all data. This will need to match the 
major/minor version of the Perforce instance.

Other projects do *not* have to follow this convention. Instead, they should
attempt to follow a strict semantic versioning mechanism:

- Major version number indicate a breaking change in the API. 
- Minor version numbers indicate an addition, that shouldn't break any existing clients.
- Release numbers just indicate a new release, probably for bug fixes.


## Build Automation

Builds are performed in a salt cluster, one per each supported platform.

Each build starts with the build machine syncing to a new changelist number.
Package files are then synced to a test machine, where we install the next
set of packages.

Tests are then run from the build master against the updated test environment.

### Machine Setup

First steps are to change the hostname and add the perforce user as a nopasswd
sudoer:

    $ sudo visudo
    
Then add this line
    
    perforce ALL=(ALL:ALL) NOPASSWD:ALL

Ubuntu 12 environments:

1. First, update and upgrade the system

2. Install vim

3. Add the public key to the pkg-ondemand repo

        $ wget -q http://pkg-ondemand.bnr.perforce.com/perforce.pubkey -O - | sudo apt-key add -

4. Create the apt source

        $ sudo bash -c 'echo deb http://pkg-ondemand.bnr.perforce.com/perforce/r15.1/apt/ubuntu precise release > /etc/apt/sources.list.d/perforce.sources.list'
        $ sudo apt-get update
        
5. Install the perforce server

        $ sudo apt-get install perforce-server


## Notes on Automated builds

Everything runs on the `master` node.

This may not need to be done each time:

    sudo salt-key -A
    sudo salt -G 'node_type:buildmaster' state.highstate
    sudo salt -G 'node_type:build' state.highstate

Create p4ws.tgz

    cd /home/$USER/p4ws
    /home/$USER/.rvm/wrappers/ruby-2.2.2@build/bundle install
    /home/$USER/.rvm/wrappers/ruby-2.2.2@build/bundle exec rake clean package

Push the source tree and build packages

TODO need to build p4ruby 
TODO need to blow away the gemset on the build machines when done

    sudo salt-cp -G 'node_type:build' pkg/p4ws.tgz /var/tmp
    sudo salt -G 'node_type:build' cmd.run 'tar xvz -C /var/tmp -f /var/tmp/p4ws.tgz' runas='vagrant'

    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/bundle install' runas='vagrant' cwd='/var/tmp/p4ws/p4ruby'
    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/rake gem' runas='vagrant' cwd='/var/tmp/p4ws/p4ruby'
    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/gem install pkg/p4ruby-*.gem' runas='vagrant' cwd='/var/tmp/p4ws/p4ruby'

    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/bundle install' runas='vagrant' cwd='/var/tmp/p4ws/p4_web_services_auth'
    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/rake install' runas='vagrant' cwd='/var/tmp/p4ws/p4_web_services_auth'
    
    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/bundle package' runas='vagrant' cwd='/var/tmp/p4ws/p4_web_api/p4_web_api'

    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/bundle install' runas='vagrant' cwd='/var/tmp/p4ws/p4_web_api/omnibus-p4_web_api'
    sudo salt -G 'node_type:build' cmd.run '/home/vagrant/.rvm/wrappers/ruby-2.2.2@build/bundle exec omnibus build p4_web_api' runas='vagrant' cwd='/var/tmp/p4ws/p4_web_api/omnibus-p4_web_api'

    sudo salt -G 'node_type:build' cp.push '/var/tmp/p4ws/p4_web_api/omnibus-p4_web_api/pkg/p4-web-api_2015.1.0-1_amd64.deb'

    sudo salt -G 'node_type:build' cmd.run 'rm -rf /var/tmp/p4ws*'
    sudo salt -G 'node_type:build' cmd.run 'rm -rf /opt/perforce/web-services'

    sudo salt -G 'node_type:build' cmd.run 'source /usr/local/rvm/scripts/rvm; rvm --force gemset delete build' runas='vagrant' shell='/bin/bash'
    sudo salt -G 'node_type:build' cmd.run 'source /usr/local/rvm/scripts/rvm; rvm gemset create build' runas='vagrant' shell='/bin/bash'

Copy .deb files to the test environment and let it reinstall

    sudo salt-cp -G 'node_type:eval' /var/cache/salt/master/minions/build-ubuntu12/files/var/tmp/p4ws/p4_web_api/omnibus-p4_web_api/pkg/p4-web-api_2015.1.0-1_amd64.deb /var/tmp
    sudo salt -G 'node_type:eval' state.highstate

Seed test data

    gem install p4util
    p4util init -p 172.16.100.11:1666 p4init

Run tests

    P4_WEB_API_PORT=172.16.100.11 bundle exec rake test:p4_web_api

Shutdown and uninstall