Differential D976

readme: update links, add testcloud to default deps
ClosedPublic
Actions

Authored by kparal on Aug 18 2016, 3:28 PM.

Details

Reviewers
mkrizek
Group Reviewers
libtaskotron
Commits
rLTRNaf49d5abedb2: readme: update links, add testcloud to default deps
Summary

Testcloud is needed for running the test suite, install it by default.
Install it from RPM rather than git, git version is generally needed for
libtaskotron development.

Update descriptions, links, examples.

Test Plan

none

Diff Detail

Repository
rLTRN libtaskotron
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
kparal retitled this revision from to readme: update links, add testcloud to default deps.Aug 18 2016, 3:28 PM
kparal updated this object.
kparal edited the test plan for this revision. (Show Details)
kparal added a reviewer: libtaskotron.
mkrizek accepted this revision.Aug 19 2016, 8:37 AM
mkrizek added a reviewer: mkrizek.
This revision is now accepted and ready to land.Aug 19 2016, 8:37 AM
Closed by commit rLTRNaf49d5abedb2: readme: update links, add testcloud to default deps (authored by kparal). · Explain WhyAug 19 2016, 9:05 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents

PathPackages
Mreadme.rst (73 lines)

Diff 2498

View Options

readme.rst

1============ 1​============
2libtaskotron 2​libtaskotron
3============ 3​============
4 4​
5libtaskotron is a library for running automated tasks as part of the 5​libtaskotron is a library for running automated tasks as part of the Taskotron_
6`Taskotron <https://fedoraproject.org/wiki/Taskotron>`_ system. It is in very 6​system. The initial objective is (but is not limited to) automating selected
7early stages of development with the initial objective of (but not limited to) 7​package checks in Fedora.
8replacing AutoQA for automating selected package checks in Fedora. 8​
9 9​The project is not yet to be considered stable - the features contained are
10Libtaskotron should be considered as very early alpha code - the features 10​generally functional but we will likely continue to make major changes in how
11contained are generally funcitonal but we will likely continue to make major 11​libtaskotron works.
12changes in how libtaskotron works. 12​
13​For more information and API documentation, please look at `Taskotron project
14​page`__.
13 15​
14Please direct questions and comments to either *#fedora-qa* on freenode or the 16​Please direct questions and comments to either *#fedora-qa* on freenode or the
15`qa-devel mailing list <https://admin.fedoraproject.org/mailman/listinfo/qa-devel>`_. 17​`qa-devel mailing list <https://admin.fedoraproject.org/mailman/listinfo/qa-devel>`_.
16 18​
17For more information, please reference the online documentation: 19​.. _Taskotron: https://taskotron.fedoraproject.org
18 20​__ Taskotron_
19 * `Development Version <http://libtaskotron.readthedocs.org/en/develop/>`_ ​
20 ​
21 * `Latest Release <http://libtaskotron.readthedocs.org/en/latest/>`_ ​
22 21​
23 22​
24Installing a Development Environment 23​Installing a Development Environment
25==================================== 24​====================================
26 25​
27Please consider whether you really need a libtaskotron development 26​Please consider whether you really need a libtaskotron development
28environment. Maybe you simply want to develop tests *using* libtaskotron? In 27​environment. Maybe you simply want to develop tests *using* libtaskotron? In
29that case, please follow `libtaskotron install instructions 28​that case, please follow `libtaskotron install instructions
30<https://docs.qadevel.cloud.fedoraproject.org/libtaskotron/latest/#install-libtaskotron>`_ 29​<https://docs.qadevel.cloud.fedoraproject.org/libtaskotron/latest/docs/#install-libtaskotron>`_
31instead. If you really want to develop libtaskotron itself, please continue. 30​instead. If you really want to develop libtaskotron itself, please continue.
32 31​
33For the moment, libtaskotron can't be fully installed by either pip or rpm and 32​For the moment, libtaskotron can't be fully installed by either pip or rpm and
34needs a bit of both for now. 33​needs a bit of both for now.
35 34​
36Some of the packages required for using libtaskotron are not yet available from 35​On your Fedora system, install the necessary packages::
37standard Fedora repos and the taskotron-copr repo is required:: ​
38 ​
39 sudo curl https://copr.fedorainfracloud.org/coprs/tflink/taskotron/repo/fedora-23/tflink-taskotron-fedora-23.repo \ ​
40 -o /etc/yum.repos.d/tflink-taskotron-fedora-23.repo ​
41 36​
42Once the copr repo is available, install the necessary packages:: 37​ sudo dnf install \
43 ​
44 sudo yum install \ ​
45 createrepo \ 38​ createrepo \
46 gcc \ 39​ gcc \
47 git \ 40​ git \
48 koji \ 41​ koji \
49 libtaskotron-config \ 42​ libtaskotron-config \
50 mash \ 43​ mash \
51 python-doit \ 44​ python-doit \
52 python-hawkey \ 45​ python-hawkey \
53 python-pip \ 46​ python-pip \
54 python-rpmfluff \ 47​ python-rpmfluff \
55 python-virtualenv \ 48​ python-virtualenv \
56 rpm-build \ 49​ rpm-build \
57 rpm-python 50​ rpm-python \
51​ testcloud
58 52​
59If you have not yet cloned the repository, do it now:: 53​If you have not yet cloned the repository, do it now::
60 54​
61 git clone https://bitbucket.org/fedoraqa/libtaskotron 55​ git clone https://bitbucket.org/fedoraqa/libtaskotron
62 cd libtaskotron 56​ cd libtaskotron
63 57​
64Then, set up the virtualenv:: 58​Then, set up the virtualenv::
65 59​
Show All 21 Lines78and add your user to it (you'll need to re-login afterwards)::
87 sudo usermod -aG taskotron <user> 81​ sudo usermod -aG taskotron <user>
88 82​
89Now create the directories with proper permissions:: 83​Now create the directories with proper permissions::
90 84​
91 sudo install -d -m 775 -g taskotron /var/tmp/taskotron /var/log/taskotron \ 85​ sudo install -d -m 775 -g taskotron /var/tmp/taskotron /var/log/taskotron \
92 /var/cache/taskotron /var/lib/taskotron /var/lib/taskotron/artifacts \ 86​ /var/cache/taskotron /var/lib/taskotron /var/lib/taskotron/artifacts \
93 /var/lib/taskotron/images 87​ /var/lib/taskotron/images
94 88​
95If you're going to run tasks using disposable VM machines, you'll also ​
96need to install `testcloud <https://github.com/Rorosha/testcloud>`_ (while ​
97being in the same virtualenv):: ​
98 ​
99 git clone https://github.com/Rorosha/testcloud.git ​
100 cd testcloud ​
101 pip install . ​
102 ​
103Read testcloud's README file to see how to configure it. ​
104 ​
105 89​
106Configuration 90​Configuration
107============= 91​=============
108 92​
109The ``libtaskotron-config`` package installs config files with default values 93​The ``libtaskotron-config`` package installs config files with default values
110into ``/etc/taskotron``. If you need to change those default values, you can 94​into ``/etc/taskotron``. If you need to change those default values, you can
111either change the files in ``/etc/taskotron`` or you can create config files 95​either change the files in ``/etc/taskotron`` or you can create config files
112inside your checkout with:: 96​inside your checkout with::
Show All 11 Lines
124 108​
125Running a Task 109​Running a Task
126============== 110​==============
127 111​
128A relatively simple example task is `rpmlint <https://bitbucket.org/fedoraqa/task-rpmlint>`_. 112​A relatively simple example task is `rpmlint <https://bitbucket.org/fedoraqa/task-rpmlint>`_.
129 113​
130The task requires the rpmlint tool to be installed, so be sure to run:: 114​The task requires the rpmlint tool to be installed, so be sure to run::
131 115​
132 sudo yum install rpmlint 116​ sudo dnf install rpmlint
133 117​
134To run that task against a koji build with NEVR ``<nevr>`` for some arch 118​To run that task against a koji build with NEVR ``<nevr>`` for some arch
135``<arch>``, do the following:: 119​``<arch>``, do the following::
136 120​
137 git clone https://bitbucket.org/fedoraqa/task-rpmlint.git 121​ git clone https://bitbucket.org/fedoraqa/task-rpmlint.git
138 runtask -i <nevr> -t koji_build -a <arch> task-rpmlint/runtask.yml 122​ runtask -i <nevr> -t koji_build -a <arch> task-rpmlint/runtask.yml
139 123​
140This will download the ``<nevr>`` from koji into a temp directory under 124​This will download the ``<nevr>`` from koji into a temp directory under
141``/var/tmp/``, run rpmlint on the downloaded rpms and print output in YAML format 125​``/var/tmp/taskotron/``, run rpmlint on the downloaded rpms and print output in
142to stdout. 126​YAML format to stdout.
143 127​
144Example:: 128​Example::
145 129​
146 runtask -i xchat-2.8.8-21.fc20 -t koji_build -a x86_64 task-rpmlint/runtask.yml 130​ runtask -i htop-2.0.2-1.fc24 -t koji_build -a x86_64 task-rpmlint/runtask.yml
147 131​
148 132​
149Using Disposable Clients for Task Execution 133​Using Disposable Clients for Task Execution
150=========================================== 134​===========================================
151 135​
152When executing the task on the local machine is not desirable, you can use the 136​When executing the task on the local machine is not desirable, you can use the
153disposable client feature - a new virtual machine is spawned from a base image 137​disposable client feature - a new virtual machine is spawned from a base image
154and the task is executed in the VM. 138​and the task is executed in the VM.
155 139​
156Note: you need to setup Testcloud first refer to `Setting up Testcloud`_ 140​Note: you need to setup Testcloud first refer to `Setting up Testcloud`_
157 141​
158To use the feature, just add ``--libvirt`` parameter ot the runtask command:: 142​To use the feature, just add ``--libvirt`` parameter to the runtask command::
159 143​
160 runtask --libvirt -i xchat-2.8.8-21.fc20 -t koji_build -a x86_64 task-rpmlint/runtask.yml 144​ runtask --libvirt -i htop-2.0.2-1.fc24 -t koji_build -a x86_64 task-rpmlint/runtask.yml
161 145​
162By default, a base image defined by the ``imageurl`` option in ``taskotron.yaml`` 146​By default, a base image defined by the ``imageurl`` option in ``taskotron.yaml``
163config file is used. You can provide your own base image by changing the 147​config file is used. You can provide your own base image by changing the
164``imageurl`` value (use ``file://`` URL to point to a local file). 148​``imageurl`` value (use ``file://`` URL to point to a local file).
165 149​
166We also provide updated base images at https://tflink.fedorapeople.org/taskotron/taskotron-cloud/images/ 150​We also provide updated base images at https://tflink.fedorapeople.org/taskotron/taskotron-cloud/images/
167(note that the image needs to be uncompressed before use). 151​(note that the image needs to be uncompressed before use).
168 152​
169If you store these images in ``/var/lib/taskotron/images``, adhere to their 153​If you store these images in ``/var/lib/taskotron/images``, adhere to their
170naming conventions and set ``force_imageurl=False`` in ``taskotron.yaml``, 154​naming conventions and set ``force_imageurl=False`` in ``taskotron.yaml``,
171we will find the latest one available automatically for you and you don't need 155​we will find the latest one available automatically for you and you don't need
172to update the ``imageurl`` option regularly. 156​to update the ``imageurl`` option regularly.
173 157​
174 158​
175Setting up Testcloud 159​Setting up Testcloud
176-------------------- 160​--------------------
177 161​
178Fedora 23 or newer is required for Testcloud to work. ​
179 ​
180Install testcloud:: ​
181 ​
182 dnf install testcloud ​
183 ​
184Configure ssh key for Testcloud to use (the private key must be passwordless). 162​Configure ssh key for Testcloud to use (the private key must be passwordless).
185Edit ``~/.config/testcloud/settings.py`` or ``/etc/testcloud/settings.py`` and 163​Edit ``~/.config/testcloud/settings.py`` or ``/etc/testcloud/settings.py`` and
186insert the respective public key in the place of the ``$SSH PUBKEY HERE$`` 164​insert the respective public key in the place of the ``$SSH PUBKEY HERE$``
187string:: 165​string::
188 166​
189 USER_DATA = """#cloud-config 167​ USER_DATA = """#cloud-config
190 users: 168​ users:
191 - default 169​ - default
192 - name: root 170​ - name: root
193 password: %s 171​ password: %s
194 chpasswd: { expire: False } 172​ chpasswd: { expire: False }
195 ssh-authorized-keys: 173​ ssh-authorized-keys:
196 - $SSH PUBKEY HERE$ 174​ - $SSH PUBKEY HERE$
197 """ 175​ """
198 176​
177​
199Running the Test Suite 178​Running the Test Suite
200====================== 179​======================
201 180​
202You can run the included test suite of unit and functional tests. 181​You can run the included test suite of unit and functional tests.
203From the root checkout directory, execute:: 182​From the root checkout directory, execute::
204 183​
205 py.test testing/ 184​ py.test testing/
206 185​
Show All 25 Lines
232 211​
233The documentation is easy to build if you have followed the instructions to set 212​The documentation is easy to build if you have followed the instructions to set
234up a development environment. 213​up a development environment.
235 214​
236To actually build the documentation:: 215​To actually build the documentation::
237 216​
238 doit builddocs 217​ doit builddocs
239 218​
219​
240Build Automation 220​Build Automation
241================ 221​================
242 222​
243There are several development related tasks which are at least somewhat 223​There are several development related tasks which are at least somewhat
244automated using `doit <http://pydoit.org/>`_ which has repaced our old Makefile. 224​automated using `doit <http://pydoit.org/>`_.
245 ​
246**Note**: Until `bug 1257936 <https://bugzilla.redhat.com/show_bug.cgi?id=1257936>`_ ​
247is resolved, you need to install ``python-configparser`` dependency manually. ​
248 225​
249After either installing the doit package (``python-doit``, ``python3-doit``) or 226​After either installing the doit package (``python-doit``, ``python3-doit``) or
250via pip (``pip install doit``), you can see a list of available tasks and a short 227​via pip (``pip install doit``), you can see a list of available tasks and a short
251description of those tasks by running ``doit list``. Some of the available tasks 228​description of those tasks by running ``doit list``. Some of the available tasks
252are: 229​are:
253 230​
254 * ``buildsrpm`` takes a snapshot of current git repo and uses the in-repo spec 231​ * ``buildsrpm`` takes a snapshot of current git repo and uses the in-repo spec
255 file to build a matching srpm in the ``builds/<version>`` directory. Note 232​ file to build a matching srpm in the ``builds/<version>`` directory. Note
Show All 11 Lines