tutorial, PR #760: Add Dockerfile and documentation for Buildbot Pyfl…

…akes tutorial.

master/contrib/Dockerfile

@@ -0,0 +1,103 @@
+# This file is part of Buildbot.  Buildbot is free software: you can
+# redistribute it and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, version 2.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program; if not, write to the Free Software Foundation, Inc., 51
+# Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# Copyright Buildbot Team Members
+#
+#
+# VERSION         1.1
+# DOCKER_VERSION  0.6.1-dev
+# AUTHOR          Daniel Mizyrycki <daniel@dotcloud.com>
+# DESCRIPTION     Build buildbot tutorial into a runnable linux container
+#                 with all dependencies installed as a playground sandbox
+#
+# # To build:
+#
+# # Install docker (http://docker.io)
+#
+# # Download buildbot Dockerfile
+# wget https://raw.github.com/buildbot/buildbot/master/master/contrib/Dockerfile
+#
+# # Build buildbot image
+# docker build -t buildbot - < Dockerfile
+#
+# # Run buildbot
+# CONTAINER_ID=$(docker run -d buildbot)
+#
+# # Test buildbot master is listening
+# wget -qO- localhost:8010
+#
+# # See buildbot in action.
+# # Browse the url localhost:8010
+# # Log into the web GUI (username: pyflakes   password: pyflakes)
+# # Click on the Waterfall link (http://localhost:8010/waterfall)
+# #   runtests builder should be idle
+# # Click on runtests builder link (http://localhost:8010/builders/runtests)
+# # Click on Force Build
+# # Click on Waterfall link again (http://localhost:8010/waterfall)
+# # If everything went well, you should be greeted with a green build.
+#
+# # From here, you can log into the docker container to understand better what
+# # is happening behind the scenes, play with master.cfg in a safe sandbox and
+# # make your buildbot playground useful for your own projects.
+#
+# # Log into container  (username: admin   password: admin)
+# ssh -p $(docker port $CONTAINER_ID 22) admin@localhost
+#
+# Base docker image
+from ubuntu:12.04
+
+# Make dpkg happy with the upstart issue
+run dpkg-divert --local --rename --add /sbin/initctl
+run ln -s /bin/true /sbin/initctl
+
+# Install buildbot and its dependencies
+run echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > \
+    /etc/apt/sources.list
+run apt-get update
+run DEBIAN_FRONTEND=noninteractive apt-get install -y python-pip python-dev \
+    supervisor git sudo ssh
+run pip install sqlalchemy==0.7.9 buildbot buildbot_slave
+
+# Set ssh superuser (username: admin   password: admin)
+run mkdir /data /var/run/sshd
+run useradd -m -d /data/buildbot -p sa1aY64JOY94w admin
+run sed -Ei 's/adm:x:4:/admin:x:4:admin/' /etc/group
+run sed -Ei 's/(\%admin ALL=\(ALL\) )ALL/\1 NOPASSWD:ALL/' /etc/sudoers
+
+# Create buildbot configuration
+run cd /data/buildbot; sudo -u admin sh -c "buildbot create-master master"
+run cp -a /data/buildbot/master/master.cfg.sample \
+    /data/buildbot/master/master.cfg
+run cd /data/buildbot; sudo -u admin sh -c \
+    "buildslave create-slave slave localhost:9989 example-slave pass"
+
+# Set supervisord buildbot and sshd processes
+run /bin/echo -e "[program:sshd]\ncommand=/usr/sbin/sshd -D\n" > \
+    /etc/supervisor/conf.d/sshd.conf
+run /bin/echo -e "\
+[program:buildmaster]\n\
+command=twistd --nodaemon --no_save -y buildbot.tac\n\
+directory=/data/buildbot/master\n\
+user=admin\n\n\
+[program:buildworker]\n\
+command=twistd --nodaemon --no_save -y buildbot.tac\n\
+directory=/data/buildbot/slave\n\
+user=admin\n" > \
+    /etc/supervisor/conf.d/buildbot.conf
+
+# Setup running docker container buildbot process
+# Make host port 8010 match container port 8010
+expose :8010
+# Expose container port 22 to a random port in the host.
+expose 22
+cmd ["/usr/bin/supervisord", "-n"]

master/docs/relnotes/index.rst

@@ -101,6 +101,9 @@ Features
 * The Git step now uses the `git clean` option `-f` twice, to also remove untracked directories managed by another git repository.
   See :bb:bug:`2560`.
 
+* Introduce an alternative way to deploy Buildbot and try the pyflakes tutorial
+  using :ref:`Docker <first-run-docker-label>`.
+
 Deprecations, Removals, and Non-Compatible Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

master/docs/tutorial/docker.rst

@@ -0,0 +1,78 @@
+.. _first-run-docker-label:
+
+==============================
+First Buildbot run with Docker
+==============================
+
+Docker_ is an awesome tool that makes building and deploying custom environments
+a breeze. It uses light linux containers and perform fast, making it a great
+instrument for the testing community.
+The next section includes a Docker pre-flight check. If it takes more that 3
+minutes to get the 'Success' message for you, please return to the Buildbot
+pip-based :ref:`first run <getting-code-label>`.
+
+.. _Docker: http://www.docker.io
+
+
+Current Docker dependencies
+---------------------------
+
+* Linux system, with at least kernel 3.8 and AUFS support. For example,
+  Standard Ubuntu, Debian and Arch systems.
+* Packages: lxc, iptables, ca-certificates, and bzip2 packages
+* Local clock on time or slightly in the future for proper SSL communication
+* Download, launch and test docker is happy in your linux enviroment:
+
+.. code-block:: bash
+
+  mkdir tmp; cd tmp
+  wget -O docker http://get.docker.io/builds/Linux/x86_64/docker-latest
+  chmod 755 docker; sudo ./docker -d &
+  sudo ./docker run -i busybox /bin/echo Success
+
+
+Building and running Buildbot
+-----------------------------
+
+.. code-block:: bash
+
+  # Download Buildbot Dockerfile.
+  wget https://raw.github.com/buildbot/buildbot/master/master/contrib/Dockerfile
+
+  # Build the Buildbot container (it will take a few minutes to download packages)
+  sudo ./docker build -t buildbot - < Dockerfile
+
+  # Run buildbot
+  CONTAINER_ID=$(sudo ./docker run -d buildbot)
+
+
+You should now be able to go to http://localhost:8010 and see a web page
+similar to:
+
+.. image:: _images/index.png
+   :alt: index page
+
+Click on the
+`Waterfall Display link <http://localhost:8010/waterfall>`_
+and you get this:
+
+.. image:: _images/waterfall-empty.png
+   :alt: empty waterfall.
+
+
+Playing with your Buildbot container
+------------------------------------
+
+If you've got this far, you have a great playground at your fingertips where
+you can effortlessly learn Buildbot and tweak its configuration to meet your needs.
+
+You can access your container using ssh  (username: admin   password: admin):
+
+.. code-block:: bash
+
+  ssh -p $(sudo ./docker port $CONTAINER_ID 22) admin@localhost
+
+
+You've got a taste now, but you're probably curious for more.  Let's step it
+up a little in the second tutorial by changing the configuration and doing
+an actual build. Continue on to :ref:`quick-tour-label`

master/docs/tutorial/firstrun.rst

@@ -18,8 +18,14 @@ the system.  In this tutorial no configuration or code changes are done.
 This tutorial assumes that you are running on Unix, but might be adaptable
 easily to Windows.
 
-*For the quickest way through, you should be able to cut and paste each shell
-block from this tutorial directly into a terminal.*
+For the :ref:`fastest way through in Linux <first-run-docker-label>`, you
+can use Docker, the linux container engine. Docker automates all the
+deployment steps for you.
+
+For a more manual approach, you should be able to cut and paste each shell
+block from this tutorial directly into a terminal.
+
+.. _getting-code-label:
 
 Getting the code
 ----------------
@@ -164,7 +170,7 @@ a web page similar to:
 .. image:: _images/index.png
    :alt: index page
 
-Click on the 
+Click on the
 `Waterfall Display link <http://localhost:8010/waterfall>`_
 and you get this:
 

master/docs/tutorial/index.rst

@@ -7,5 +7,6 @@ Contents:
    :maxdepth: 2
 
    firstrun
+   docker
    tour
    further