A virtual building and testing environment using Vagrant

This patch provides all necessary files and configurations to
build a Vagrantbox that can be used as building and testing
environment for all OpenStack manuals and documentations. It
includes the repositories like openstack-manuals. Tox, Maven
and all needed dependencies by Maven are already
installed/fetched.

Change-Id: Ic7a496ee16efffc7ae41f657a07af998436ea12e
Closes-Bug: #1317849

.gitignore

@@ -30,3 +30,7 @@ autogenerate_config_docs/*-conf-changes-*.xml
 
 # sitemap
 sitemap/sitemap_docs.openstack.org.xml
+
+# build and test environment
+build_environment/.vagrant/
+build_environment/repositories/

RELEASE_NOTES.rst

@@ -8,6 +8,7 @@ Release notes
 * ``openstack-dn2osdbk``: Allow single files as source
 * Imported and improved ``doc-tools-check-languages`` (recently known
   as ``tools/test-languages.sh`` in the documentation repositories).
+* Added a virtual build and test environment based on Vagrant.
 
 0.17
 ----

build_environment/README.md

@@ -0,0 +1,75 @@
+# Virtual build and testing environment
+
+This is a virtual building and testing environment for the
+OpenStack manuals using Vagrant to simplify the work.
+
+## Getting started with Vagrant
+
+* download a Vagrant package from http://www.vagrantup.com/downloads.html
+* install and configure Vagrant like described
+  at http://docs.vagrantup.com/v2/installation/index.html
+
+## Build your own environment
+
+To manually build your own environment you have to follow the following
+steps.
+
+Ansible (http://www.ansible.com/home) needs to be installed on the
+workstation.
+
+```
+$ git clone https://github.com/openstack/openstack-doc-tools
+$ cd openstack-doc-tools/build_environment
+$ vagrant up
+```
+
+After ```vagrant up``` successfully finished you can login with
+```vagrant ssh```. The virtual system can be destroyed with
+```vagrant destroy```.
+
+## Use the Vagrantbox from the VagrantCloud
+
+Using the prebuilt box for VirtualBox on the VagrantCloud saves
+a lot of time and you don't need to install Ansbile. Simply
+follow the following steps:
+
+```
+$ vagrant box add openstack/openstack-manuals
+$ mkdir /path/to/your/vagrantbox
+$ cd /path/to/your/vagrantbox
+$ vagrant init openstack/openstack-manuals
+$ vagrant up
+```
+
+## Usage
+
+To test and build the documents login into the box. The generated
+files are browsable at http://localhost:8080/.
+
+```
+$ vagrant ssh
+```
+
+Go into the repositories located in ```/home/vagrant/repositories```
+and build the documents with ```mvn clean generate-sources```.
+
+To edit the documents and to commit changes you can use the toolchain
+on the workstation. All repositories can be found in the local
+directory ```repositories```. This directory is available inside the
+virtual system at ```/home/vagrant/repositories```.
+
+## Included repositories
+
+* api-site
+* compute-api
+* identity-api
+* image-api
+* netconn-api
+* object-api
+* openstack-doc-tools
+* openstack-manuals
+* volume-api
+
+## Caveats
+
+* At the moment the only tested provider is VirtualBox.

build_environment/Vagrantfile

@@ -0,0 +1,32 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+Vagrant.configure(2) do |config|
+  config.vm.box = "ubuntu/trusty64"
+  config.vm.hostname = "manuals.site"
+
+  config.vm.provider "virtualbox" do |vb|
+    vb.customize ['modifyvm', :id, '--memory', 1024]
+    vb.customize ['modifyvm', :id, '--cpus', 2]
+  end
+
+  # access the webserver from your workstation
+  config.vm.network "forwarded_port", guest: 80, host: 8080
+
+  # create the local repositories directory (available as /opt/repositories
+  # inside the virtual system)
+  Dir.mkdir('repositories') unless Dir.exists?('repositories')
+
+  # repositories live here
+  config.vm.synced_folder "repositories", "/home/vagrant/repositories"
+
+  # cache distribution packages when cachier plugin is available
+  if Vagrant.has_plugin?("vagrant-cachier")
+    config.cache.scope = :box
+  end
+
+  # provision the virtual system using Ansible
+  config.vm.provision "ansible" do |ansible|
+    ansible.playbook = "files/playbook.yaml"
+  end
+end

build_environment/Vagrantfile.box

@@ -0,0 +1,25 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# NOTE(berendt): This is the Vagrantfile included with the box provided
+#                on the Vagrant cloud as openstack/openstack-manuals. The
+#                box is created with the script package.sh.
+
+filename = File.expand_path("../repositories.tar.bz2", __FILE__)
+if not File.exists?('repositories/.placeholder')
+  system("tar xjf #{filename}")
+end
+
+Vagrant.configure(2) do |config|
+  config.vm.box = "openstack/openstack-manuals"
+  config.vm.hostname = "manuals.site"
+  config.vm.network "forwarded_port", guest: 80, host: 8080
+  config.vm.provider "virtualbox" do |vb|
+    vb.customize ['modifyvm', :id, '--memory', 1024]
+    vb.customize ['modifyvm', :id, '--cpus', 2]
+  end
+  config.vm.synced_folder "repositories", "/home/vagrant/repositories", create: true
+  if Vagrant.has_plugin?("vagrant-cachier")
+    config.cache.scope = :box
+  end
+end

build_environment/bin/package.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# Just a helper script to package a running Vagrant environment.
+
+if [[ -z $1 ]]; then
+    echo "usage: $0 VERSION"
+    exit 1
+fi
+
+version=$1
+rm -f working.tar.bz2
+touch working/.placeholder
+tar cjf working.tar.bz2 working
+vagrant package \
+  --output=openstack-manuals-$version.box \
+  --vagrantfile=Vagrantfile.box \
+  --include working.tar.bz2

build_environment/files/fetch.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+set -x
+
+# This script downloads all dependencies to be able
+# to build the documents.
+
+for repository in $(ls -d -1 /home/vagrant/repositories/*); do
+  cd $repository
+  for document in $(find . -name pom.xml); do
+    pushd ${document%/*};
+    mvn clean generate-sources
+    mvn clean
+    popd
+  done
+done

build_environment/files/nginx.default

@@ -0,0 +1,22 @@
+server {
+  listen 80 default_server;
+  listen [::]:80 default_server ipv6only=on;
+
+  root /home/vagrant/repositories;
+  index index.html index.htm;
+
+  server_name manuals.site;
+
+  location / {
+    autoindex on;
+    autoindex_exact_size on;
+    try_files $uri $uri/ =404;
+  }
+
+  location /openstack-manuals/doc {
+    index local-files.html;
+    autoindex on;
+    autoindex_exact_size on;
+    try_files $uri $uri/ =404;
+  }
+}

build_environment/files/playbook.yaml

@@ -0,0 +1,47 @@
+---
+- hosts: all
+  sudo: True
+
+  tasks:
+  - apt: update_cache=yes
+  - apt: upgrade=dist
+  - apt: name={{ item }} state=present
+    with_items:
+    - git
+    - git-review
+    - maven
+    - nginx
+    - python-tox
+
+  - copy: src=nginx.default dest=/etc/nginx/sites-available/default
+    notify: restart nginx
+  - service: name=nginx enabled=yes state=started
+
+  - copy: src=fetch.sh dest=/usr/local/bin/fetch.sh mode=0755
+
+  - lineinfile: dest=/etc/environment regexp='^JAVA_HOME=' line='JAVA_HOME=/usr/lib/jvm/default-java'
+    sudo: True
+
+  - git: repo=https://github.com/openstack/{{ item }} dest=/home/vagrant/repositories/{{ item }}
+    with_items:
+    - api-site
+    - compute-api
+    - docs-specs
+    - identity-api
+    - image-api
+    - netconn-api
+    - object-api
+    - openstack-doc-tools
+    - openstack-manuals
+    - operations-guide
+    - security-doc
+    - training-guides
+    - volume-api
+    sudo: False
+
+  - command: /usr/local/bin/fetch.sh
+    sudo: False
+
+  handlers:
+  - name: restart nginx
+    service: name=nginx state=restarted