popolnik.xhtml

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:svg="http://www.w3.org/2000/svg">
<head>
<title>Popolnik README</title>
<style type="text/css">
html {font-family: Sans-Serif}
h1 {text-align: center}
pre {background-color: lightgray}
</style>
</head>
<body>

<!-- mention cpantesters -->
<h1>
Popolnik
</h1>

"Have a smoke, it's good for us"

<h2>
Overview
</h2>

<svg:svg viewBox="0 0 1000 150" width="100%" version="1.2" baseProfile="tiny">
    <svg:path d="M400,50 C400,20 600,20 600,50" stroke="black" stroke-width="1" fill="none"/>
    <svg:path d="M400,50 C400,80 600,80 600,50" stroke="black" stroke-width="1" fill="none"/>
    <svg:ellipse cx="500" cy="50" rx="60" ry="10" fill="black"/>
    <svg:line    x1="400" y1="50" x2="400" y2="90" stroke="black" stroke-width="1"/>
    <svg:line    x1="600" y1="50" x2="600" y2="90" stroke="black" stroke-width="1"/>
    <svg:path     d="M400,90 C400,120 600,120 600,90" stroke="black" stroke-width="1" fill="none"/>
    <svg:line    x1="410" y1="40" x2="452" y2="45" stroke="black" stroke-width="1"/>
    <svg:line    x1="406" y1="43" x2="448" y2="48" stroke="black" stroke-width="1"/>
    <svg:line    x1="548" y1="52" x2="594" y2="57" stroke="black" stroke-width="1"/>
    <svg:line    x1="552" y1="55" x2="590" y2="60" stroke="black" stroke-width="1"/>
</svg:svg>
<br/>

You may have heard of "smoke testing".  In hardware, it means "turn it
on and see if any smoke comes out".  You may also know that electrical
devices need "magic smoke" or "blue smoke" to work properly.  If a
component accidentally it can rupture, allowing the smoke to escape,
permanently damaging the component.
<p/>

In software, "smoke testing" means running it to see if it works or
fails.  Damage can almost always be repaired by reverting recent
changes.  Computer programmers should often perform smoke tests to check
their work.  A "smoker" is a computer and software configured to
automatically perform smoke tests.
<p/>

After you've had a smoke, you're left with a stub.  In software testing,
the stub is a test report.  You should put your stubs in an ashtray.
That is popolnik, in Slovak.
<p/>

<h3>
Security
</h3>
Did you know that smoke tests run arbitrary code on your computer?  Now
you do.
<p/>

<h2>
Architecture
</h2>

<svg:svg viewBox="0 0 1000 150" width="100%" version="1.2" baseProfile="tiny">
    <svg:path d="M400,50 C400,20 600,20 600,50" stroke="black" stroke-width="1" fill="none"/>
    <svg:path d="M400,50 C400,80 600,80 600,50" stroke="black" stroke-width="1" fill="none"/>
    <svg:ellipse cx="500" cy="50" rx="60" ry="10" fill="black"/>
    <svg:line    x1="400" y1="50" x2="400" y2="90" stroke="black" stroke-width="1"/>
    <svg:line    x1="600" y1="50" x2="600" y2="90" stroke="black" stroke-width="1"/>
    <svg:path     d="M400,90 C400,120 600,120 600,90" stroke="black" stroke-width="1" fill="none"/>
    <svg:line    x1="410" y1="40" x2="452" y2="45" stroke="black" stroke-width="1"/>
    <svg:line    x1="406" y1="43" x2="448" y2="48" stroke="black" stroke-width="1"/>
    <svg:line    x1="548" y1="52" x2="594" y2="57" stroke="black" stroke-width="1"/>
    <svg:line    x1="552" y1="55" x2="590" y2="60" stroke="black" stroke-width="1"/>
</svg:svg>
<br/>

The foundation of popolnik is an SQL database containing test results.
Smokers put their stubs into popolnik by uploading via scp.  Popolnik
validates the uploads and imports the data.  Any Perl 6 developer can
choose to become a smoker by running a few simple scripts.  Whilst much
detailed information is uploaded, care is taken to preserve anonymity,
so nobody else needs to know that you are a smoker.  That avoids the
"but I didn't inhale" crap.  You can also stop or resume smoking
whenever you want.
<p/>

Many software products can be tested because the reports are based on
TAP, the Test Anything Protocol.  The initial products are Perl 6
implementations such as Rakudo, and Perl 6 modules.  Parrot, Perl 5, all
their modules and any other TAP application should fit in as well.  To
prevent an overflow, popolnik restricts uploaded stubs with quotas and
filters.  Fortunately the rejected stubs disappear, rather than spilling
onto the table or the floor.
<p/>

To minimize overheads, the central server does not generally perform end
user queries.  Instead, popolnik exports incremental consolidated data
updates hourly into compressed text files.  Subscribers keep copies of
the data synchronized by selectively downloading and importing these
files into their own databases to extract information locally.  Popolnik
includes popular reports and facilities for local customization.  A
separate public web server might also publish results but that is
peripheral to popolnik.
<p/>

To curb data explosion, hourly export files are deleted from the central
server after a configurable number of days.  Daily summary export files
are deleted after a longer configurable interval and monthly summary
exports are retained indefinitely, but may be manually deleted by
administrators.  All the data still remains in the central database to
enable custom manual exports.
<p/>

The data includes test success and failure, and also speed if that
information is available.  The Rakudo Test.pm can time each test to a
microsecond.  The data can be sliced and diced along multiple dimensions
such as versions of software involved, date and time, commit history,
hardware, operating system, and yet to be determined other factors.
<p/>

Test suites change frequently.  The TAP protocol labels each test with a
number and a description (unfortunately often missing or duplicated).
Some queries attempt to use these labels to uniquely identify tests, but
it will be trash in, trash out.  The database keeps the information in
as original a form as possible.  Client software is responsible for
making relevant comparisons.
<p/>

Popolnik publishes requests for test results that would be useful
additions to the database.  These requests are stored in a text file
downloadable from the web server, sorted from highest priority.  The
requests list is revised at irregular times, usually only after hours or
days, so smokers should refrain from hitting the server frequently.  A
'wget --timestamping --user-agent="wget-popolnik" --continue' command is
the most considerate way to stay in sync.
<p/>
In order to make the results reproducible, each line in the request file describes the item to be tested, including
versions of all required software such as Rakudo and GCC versions.
<p/>


The central server (popolnik.jnthn.net) is a VirtualBox guest running
Debian 6.0, Rakudo Star, PostgreSQL, Perl 5 and Apache.  Its install and
configure procedures are documented below.
<p/>

<h2>
Usage
</h2>

<h3>
Keeping our ashtray clean
</h3>
You may have little use for your stubs after you've had a smoke, but
Popolnik can benefit by recycling them.  Please place your clean stubs
neatly into our ashtray.  The disposal works best if your stubs are
regular and uncontaminated.  Thank you for your cooperation.
<p/>

Clean stubs from smoker clients means uploaded test result files in the
documented format and free of extraneous data.  Popolnik rejects invalid
data and logs the source, but it still wastes resources.
<p/>

Timing results are often degraded by loss of CPU time to other processes
and by external factors such as file access delays.  Popolnik tries to
mitigate these by executing the test suite twice and keeping both sets
of results.  Please run smoker tests in a temporary directory on a file system that
performs well.  Usually the second run is faster because caches contain
more of the relevant content, the computer is "warmed up".  Analysing
the difference between the two runs may give some interesting insights.
<p/>

<h2>
Host Machine Setup
</h2>

Get VirtualBox, preferably version 4.x or later.  Older versions of
VirtualBox might work, but have not (yet) been tested.
<p/>

Get the Debian 6.0 Network Install CD for
your processor architecture (available from
<a href="http://www.debian.org/CD/netinst/">http://www.debian.org/CD/netinst/</a>).
<p/>

<pre>
sudo apt-get install virtualbox-ose
sudo adduser $USERNAME vboxusers
logout         # to re-login and get new group membership
id             # should include vboxusers now
sudo modprobe vboxdrv
VBoxManage -v
echo creating vm popolnik
VBoxManage createvm -name "popolnik" -register
</pre>

<h2>
Guest Machine Creation
</h2>

With the prerequisites installed, the host computer needs approximately
800MB of disk space (or more) for virtual hard drives.
<p/>

Install Debian 6.0 with these partition sizes (or bigger):<p/>
<table id="partitions">
    <tr><th>Part #</th><th>Label</th><th>Size (MB)</th></tr>
    <tr><td>1</td><td>popolnik-squeeze</td><td>400MB</td></tr>
    <tr><td>2</td><td>popolnik-swap</td><td>100MB</td></tr>
    <tr><td>3</td><td>popolnik-home</td><td>100MB</td></tr>
    <tr><td>4</td><td>(extended partition)</td><td>200MB</td></tr>
    <tr><td>5</td><td>popolnik-uploads</td><td>100MB</td></tr>
    <tr><td>6</td><td>popolnik-database</td><td>100MB</td></tr>
</table>
<p/>

<pre>
echo setting OS type
VBoxManage modifyvm "popolnik" -ostype debian # an ID from 'VBoxManage list ostypes'
echo setting memory size
VBoxManage modifyvm "popolnik" -memory 1024   # megabytes
echo setting video memory
VBoxManage modifyvm "popolnik" -vram 8        # video memory, megabytes

echo creating a 2GB drive to install Debian and software
VBoxManage createvdi -filename "popolnik_drive0" -size 2047 -register
</pre>

Choose the targeted initrd because the boot drive is not going anywhere
else.  During Tasksel, uncheck the "standard installation", because that
brings in x11 and Gnome, and more than quadruples the size and number of
packages to install.
<p/>

After installation, log in using the root account and run
`apt-get install sudo`.  Then `adduser popolnik sudo`.  Log out of the
root session, in future use sudo.
<p/>

Log in using the popolnik account.  Run `sudo apt-get install postgresql`.
That installs about 80MB of packages.
<p/>

Install perl-doc

<h2>
Guest Machine Removal
</h2>
When you've had enough, remove it all to be able to start again

<pre>
echo unregistering
VBoxManage unregistervm "popolnik" -delete
echo removing popolnik from ~/.VirtualBox/Machines/
rm -rf ~/.VirtualBox/Machines/popolnik


# logged in to the virtual machine as root
apt-get install sudo
vi /etc/sudoers # add jnthn and martin as sudoers with all privileges
exit

# logged in to the virtual machine as root
sudo apt-get install openssh-server
sudo apt-get install perl-doc
sudo apt-get install gcc
sudo apt-get install make
sudo apt-get install git-core
sudo apt-get install subversion
sudo apt-get install libicu-dev
sudo apt-get install screen
sudo apt-get install mysql-server

# logged in as rakudo
git clone git://github.com/rakudo/rakudo.git
cd rakudo
time perl Configure.pl --gen-parrot
time make install testable
</pre>

<h2>
Smoker Software
</h2>
- config
- cron
- compilers
- modules
- versions (including rakudo and parrot)
- make test / prove / loudtest
- facter (cosimo)
- scp to popolnik
- Win32_ComputerSystem http://msdn.microsoft.com/en-us/library/aa394102%28VS.85%29.aspx
- Win32 Processor      http://msdn.microsoft.com/en-us/library/aa394373%28VS.85%29.aspx
- Perl WMI example     http://www.activexperts.com/admin/scripts/wmi/perl/0356/

<h2>
Popolnik software
</h2>
ssh-server
perl 5
POE filesystem events
timer events (export incremental updates)
PostgreSQL


<h2>
LICENSE and COPYRIGHT
</h2>
Use these files at your risk and without warranty.  Give due credit if
you do.  Written by Martin Berends.

<h2>
References
</h2>

<h3>
VirtualBox
</h3>
<a href="http://www.virtualbox.org/">http://www.virtualbox.org/</a> home page<br/>
<a href="http://www.virtualbox.org/manual/UserManual.html">http://www.virtualbox.org/manual/UserManual.html</a> user manual<br/>

<h3>
Smoke
</h3>
<a href="http://www3.telus.net/bc_triumph_registry/smoke.htm">http://www3.telus.net/bc_triumph_registry/smoke.htm</a> background information about magic smoke in cars<br/>

</body>
</html>