2014-02-26 19:48:34 +04:00
Build and Release Process
=========================
2013-07-10 23:14:03 +04:00
2014-12-03 16:43:10 +03:00
This document describes the Ansible Tower Software build and release process.
This process includes the automation of the packaging for Debian/Ubuntu and
Fedora/EL (Enterprise Linux), as well as the creation of various software
repositories which are used by the default playbook setup.
2013-07-10 23:14:03 +04:00
Packaging Details
-----------------------------
2013-07-10 23:20:04 +04:00
### Version and Release Determination ###
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
The `VERSION` and `RELEASE` variables used by the build process are configured
in the Makefile. The `VERSION` is taken from the `__version__` field contained
within the `awx/__init__.py file.` This string should always be of the format:
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
[0-9\.]+
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
There should *not* be any "-" characters contained in the string. (Which can
represent a build/rev type release number). Example:
2014-02-26 19:48:34 +04:00
2014-11-19 18:41:38 +03:00
1.2.2
The RELEASE value is generated by the Makefile during build time. While the
value can be supplied by setting the environment variable `RELEASE` , it is
recommended to let the `Makefile` determine the appropriate value.
2013-07-10 23:14:03 +04:00
2013-07-10 23:20:04 +04:00
### OFFICIAL vs. Non-OFFICIAL Builds ###
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
An "official" build is one that does not include a development timestamp in the
release field. This is controlled by setting the environment variable
2013-07-10 23:29:16 +04:00
`OFFICIAL=yes` prior to running the make command.
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
Non-official builds will replace the `RELEASE` variable with the following
string:
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
-0.gitYYYYmmDDHHMM
2013-07-10 23:14:03 +04:00
Non-official builds should only be used for development purposes, and are
copied into the nightly repos. Official builds will be copied out to the
production servers via the automated Jenkins build process (described below).
2013-07-10 23:20:04 +04:00
### Python sdist Process ###
2013-07-10 23:14:03 +04:00
The sdist build is the first step in the packaging process. This step is
responsible for assembling the files to be packaged into a .tar.gz, which
can then be installed itself via pip or used later for the RPM/DEB builds.
The resulting tar.gz file will be named:
2014-11-19 18:41:38 +03:00
ansible-tower-${VERSION}-${RELEASE}.tar.gz
2013-07-10 23:14:03 +04:00
2013-07-10 23:20:04 +04:00
### RPM Build Process ###
2013-07-10 23:14:03 +04:00
2013-07-10 23:29:16 +04:00
The first step of the RPM build process is to remove the `$RELEASE` from the
2013-07-10 23:14:03 +04:00
tar.gz, since the spec file does not like to include the release. This is
2013-07-10 23:29:16 +04:00
handled by the `rpmtar` Makefile target, which first unpacks the file, renames
2014-11-19 18:41:38 +03:00
the contained directory to simply be `ansible-tower-${VERSION}` , and finally re-
packages the file as `ansible-tower-${VERSION}.tar.gz` .
2013-07-10 23:14:03 +04:00
2013-07-10 23:29:16 +04:00
The main Makefile target for the rpm build is (unsurprisingly) `rpm` . This copies
2013-07-10 23:14:03 +04:00
the re-formed sdist .tar.gz file into the rpm-build directory and then calls
the rpmbuild command to create the RPM.
2014-11-19 18:41:38 +03:00
The spec file for this command is `packaging/rpm/ansible-tower.spec` . This file is currently
2013-07-10 23:14:03 +04:00
maintained by hand, so any changelog entries must be added to it manually. All
other aspects of the file (source, version, release, etc.) are picked up via
variables that are set by the Makefile and do not need to be updated during
packaging.
2013-07-10 23:20:04 +04:00
### DEB Build Process ###
2013-07-10 23:14:03 +04:00
The process to build a .deb is somewhat more involved, and I will not get too
involved in the specifics of how the debian packaging works. The main files used
2013-07-10 23:29:16 +04:00
in this packaging are (all found in `packaging/deb/` ):
2013-07-10 23:14:03 +04:00
2014-11-19 18:41:38 +03:00
- ansible-tower.dirs
- ansible-tower.install
2013-07-10 23:14:03 +04:00
- control
- rules
- {pre,post}{inst,rm}
2014-11-19 18:41:38 +03:00
The `ansible-tower.dirs` file contains the directories (listed as paths relative to the
2013-07-10 23:14:03 +04:00
build root) that will be created during the packaging.
2014-11-19 18:41:38 +03:00
The `ansible-tower.install` file contains a list of files that will be installed directly
2013-07-10 23:29:16 +04:00
by the build process rather than via the `make install` command or other steps. This
2013-07-10 23:14:03 +04:00
is of the format "source destination" (where the destination is also a path
relative to the build root).
2013-07-10 23:29:16 +04:00
The `control` file is functionally similar to the header of a spec file, and
2013-07-10 23:14:03 +04:00
contains things like the package name, requirements, etc.
2013-07-10 23:29:16 +04:00
The `rules` file is really a Makefile, and contains the rules for the build
2013-07-10 23:14:03 +04:00
process. These rules are based on the type of build you're executing (binary
vs. source, for instance). Since we are building a binary-only .deb package,
2013-07-10 23:41:44 +04:00
the only target we use is the `binary` target.
2013-07-10 23:14:03 +04:00
The pre/post scripts are analogous to the %pre/%post macros in the RPM spec,
and are executed at the various stages of the installation/removal. For
Debian/Ubuntu, these scripts do quite a bit more than the corresponding RPM
stages, since RPM packaging guidelines are generally more strict about
starting/stopping services, etc. during the RPM installation.
2013-07-10 23:29:16 +04:00
In the main `Makefile` , just as with the RPM target, the target for building
the .deb's is `deb` . This target begins similarly to the rpm target, in that
2013-07-10 23:14:03 +04:00
it copies the sdist file into the deb-build directory. It then unpacks that
2013-07-10 23:29:16 +04:00
file there and calls the `dh_make` helper function. This creates several new
directories that are used by the `dpkg-buildpackage` command, most importantly
the `debian` and `DEBIAN` directories (used for the source and binary builds,
respectively). The generated `debian` directory is removed and replaced with
the files that are in `packaging/deb/` and the target package name is inserted
into a file that will be used as a command-line argument to `dpkg-buildpackage` .
2013-07-10 23:14:03 +04:00
This is required, otherwise the build process will try and figure out the
name automatically (and not always successfully).
2013-07-10 23:29:16 +04:00
Finally, `dpkg-buildpackage` is called to build the .deb.
2013-07-10 23:14:03 +04:00
Jenkins
-----------------------------
2013-07-10 23:20:04 +04:00
### Server Information ###
2013-07-10 23:14:03 +04:00
2015-11-13 19:47:28 +03:00
The Ansible Jenkins server can be found at http://jenkins.testing.ansible.com
2013-07-10 23:14:03 +04:00
This is a standard Jenkins installation, with the following additional
plugins installed:
2013-07-10 23:20:04 +04:00
- Build Authorization Token Root Plugin:
2013-07-10 23:14:03 +04:00
This plugin allows build and related REST build triggers be accessed even
when anonymous users cannot see Jenkins.
2013-07-10 23:20:04 +04:00
- Git Client Plugin:
2013-07-10 23:14:03 +04:00
The standard git client plugin.
2013-07-10 23:20:04 +04:00
- Git Parameter Plug-In:
2013-07-10 23:14:03 +04:00
This plugin adds the ability to choose from git repository revisions or tags
2013-07-10 23:20:04 +04:00
- GitHub API Plugin:
2013-07-10 23:14:03 +04:00
This plugin provides GitHub API for other plugins.
2013-07-10 23:20:04 +04:00
- GitHub Plugin:
2013-07-10 23:14:03 +04:00
This plugin integrates GitHub to Jenkins.
2013-07-10 23:20:04 +04:00
- Workspace Cleanup Plugin:
2013-07-10 23:14:03 +04:00
This plugin ensures that the root of the workspace is cleaned out between
builds to prevent files from previous builds leaking or breaking future builds.
2013-07-10 23:41:44 +04:00
### Server Installation and Configuration ###
2013-07-10 23:14:03 +04:00
The base Jenkins server was installed via apt:
2013-07-10 23:20:04 +04:00
$ apt-get install jenkins
2013-07-10 23:14:03 +04:00
Since the server OS for the Jenkins server is Ubuntu Raring (13.04). In order to
execute RPM builds on this server, mock was installed from source as follows:
2013-07-10 23:20:04 +04:00
$ apt-get install \
automake \
git \
libpython2.7 \
libsqlite0 \
libuser1 \
make \
python-decoratortools \
python-libxml2 \
python-peak.util.decorators \
python-pycurl \
python-rpm \
python-sqlite \
python-sqlitecachec \
python-support \
python-urlgrabber \
usermode \
yum \
yum-utils
$ git clone git://git.fedorahosted.org/git/mock.git mock
$ cd mock
$ ./autogen.sh
$ automake
$ ./configure \
--bindir=/usr/bin \
--sbindir=/usr/sbin \
--sysconfdir=/etc \
--localstatedir=/var/lib \
--libdir=/usr/lib \
--includedir=/usr/include \
--mandir=/usr/man
$ make install
$ ln -s /usr/bin/consolehelper /usr/bin/mock
2013-07-10 23:14:03 +04:00
In order to create apt repositories, the reprepro package was also installed.
2013-07-10 23:20:04 +04:00
$ apt-get install reprepro
2013-07-10 23:14:03 +04:00
2013-07-10 23:20:04 +04:00
### Configured Jobs ###
2013-07-10 23:14:03 +04:00
There are currently three classes of jobs configured in Jenkins:
2014-12-03 16:43:10 +03:00
- `Build_Ansible_{RPM,DEB,TAR,Docs}` builds for Ansible
- `Build_Tower_{RPM,DEB,TAR,Docs}` builds for Ansible Tower
2013-07-10 23:14:03 +04:00
- Automated Scans which kick-off the prior two jobs
The automated scans work by checking for new tags in the git repository for
the given project, and when a new one is found, starting the appropriate jobs.
For RPMs, a job is started for each of the supported distributions while for
2013-07-10 23:29:16 +04:00
DEBs only one job is started. All of these jobs are started with `OFFICIAL=yes`
2013-07-10 23:14:03 +04:00
so that an official package is produced, which will be copied out to the production
repositories (documented below).
> NOTE: The nightly jobs are currently triggered by a cron job in the exact same
> manner as the above jobs, the only difference being that they set OFFICIAL=no
> and use HEAD as the target tag for the job, so they are always built off of
> the most recent commit at that time. Likewise, the resultant packages are only
> copied to the relevant nightlies repo (also documented below).
2013-07-10 23:20:04 +04:00
### Manual Builds ###
2013-07-10 23:14:03 +04:00
Manual builds can be triggered via the Jenkins GUI. Simply log in and select the
appropriate job, and then click on the "Build with Parameters" link to the left
(or select it from the drop-down that is available from the main jobs list).
2013-07-10 23:29:16 +04:00
You will be presented with a form to enter parameters. The `TARGET_TAG` and `OFFICIAL`
2013-07-10 23:14:03 +04:00
parameters are the same for both RPM and DEB builds, the function of which is
2013-07-10 23:29:16 +04:00
described above. For RPM builds, there is an addition parameter named `TARGET_DIST` ,
2013-07-10 23:14:03 +04:00
which controls the mock environment for the build.
2013-07-10 23:29:16 +04:00
> WARNING: Take extra care when manually triggering an `OFFICIAL` build at this
2013-07-10 23:14:03 +04:00
> time, as the resultant package will automatically be copied to the production
> server and made available for customers to download.
2013-07-10 23:29:16 +04:00
> NOTE: As of this writing, using the combination of `TARGET_TAG=HEAD` and `OFFICIAL=yes`
2013-07-10 23:14:03 +04:00
> is allowed, however this will not be the case in the future. This will either be
> disallowed by failing the job, or the resultant package will be copied to a third
> repository to be used for user-acceptance testing (UAT).
Repositories
-----------------------------
2013-07-10 23:20:04 +04:00
### Nightlies ###
2013-07-10 23:14:03 +04:00
The nightly repositories are hosted on the AnsibleWorks Jenkins server, and can
be found at the following location:
2017-01-31 18:43:20 +03:00
http://jenkins.testing.ansible.com/ansible-tower_nightlies_f8b8c5588b2505970227a7b0900ef69040ad5a00/devel
2013-07-10 23:14:03 +04:00
2014-12-03 16:43:10 +03:00
There are several sub-folders, including `deb/` , `rpm/` , `docs/` and `setup/`
2013-07-10 23:14:03 +04:00
2013-07-10 23:29:16 +04:00
The `rpm/` folder itself contains sub-folders for each distribution/architecture
2013-07-10 23:14:03 +04:00
that we support, for example:
- epel-6-{i386,x86_64}
2014-12-03 16:43:10 +03:00
- epel-7-{i386,x86_64}
2013-07-10 23:14:03 +04:00
2014-12-03 16:43:10 +03:00
The `deb/` folder contains several subfolders, which correspond to the normal
2013-07-10 23:29:16 +04:00
apt repository structure. All .deb files are located under `pool/` , while the `dists/`
2013-07-10 23:14:03 +04:00
directory contains the distribution-specific information.
2014-12-03 16:43:10 +03:00
The `docs/` folder contains the PDF documentation.
The `setup/` folder contains the Ansible Tower setup playbook tar.gz file.
2013-07-10 23:14:03 +04:00
2014-12-03 16:43:10 +03:00
These nightly repositories can be used by the Ansible Tower setup playbook by
running the `setup.sh` shell script with the following option:
2013-07-10 23:14:03 +04:00
2017-01-31 18:43:20 +03:00
./setup.sh -e "aw_repo_url=http://jenkins.testing.ansible.com/ansible-tower_nightlies_f8b8c5588b2505970227a7b0900ef69040ad5a00/devel gpgcheck=0"
2013-07-10 23:14:03 +04:00
2013-07-10 23:20:04 +04:00
### Official Releases ###
2013-07-10 23:14:03 +04:00
2013-07-10 23:29:16 +04:00
As noted above, `OFFICIAL` builds are copied out to the production server, and can be
2013-07-10 23:14:03 +04:00
found at the following location:
2014-01-29 21:30:12 +04:00
http://releases.ansible.com/ansible-tower/
2013-07-10 23:14:03 +04:00
2014-12-03 16:43:10 +03:00
The Ansible Tower setup playbook will use this repo location by default.
2013-07-10 23:14:03 +04:00