An XML based generator for docker environments, mostly used for automated testing.
The Joomla! Virtualisation tool generates a
docker-compose.yml file based on XML setup definitions used for - but not limited to - automated testing.
It is based on GreenCape/build.
This repository also contains a set of
Dockerfiles. Once they no longer undergo frequent changes, the images will be available on DockerHub.
Joomla! Virtualisation is work in progress. Once it has everything to really be usable, it will be available for installation through Composer.
Be sure to use recent versions of
docker-compose. The versions you get from the standard repository for Ubuntu 16.04, for example, are too outdated. Follow the official instructions for Docker Community Edition (CE) and Docker Compose to get the most recent versions.
use Joomla\Virtualisation\DockerComposeGenerator; $generator = new DockerComposeGenerator('tests/servers'); $generator->write('dockyard/docker-compose.yml');
tests/servers' is the directory containing the XML setup configurations and '
dockyard' is the docker build directory defined in the environment (see Environment /
dockyard in the next section).
Create a new directory
servers under your
tests directory. It will house the following XML files to describe server configurations.
The database credentials are expected to be in a file named
database.xml in the
<database> <mysql version="latest" name="joomla_test" user="sqladmin" password="sqladmin" rootPassword="root"/> <postgresql version="latest" name="joomla_test" user="sqladmin" password="sqladmin"/> </database>
Defines version and credentials for a MySQL (compatible) database server.
version- The version of MySQL to use. Supported are all minor versions since MySQL 5.5. Defaults to 'latest'.
name- The name of the database.
user- The name of the database user.
password- The database user’s password.
rootPassword- The database root password.
Defines version and credentials for a PostgreSQL database server.
version- The version of PostgreSQL to use. Supported are all minor versions since PostgreSQL 9.2. Defaults to 'latest'.
name- The name of the database.
user- The name of the database user.
password- The database user’s password.
<environment name="env-name"> <host dockyard="shipyard"/> <joomla version="3" sampleData="data"/> <database driver="mysql" name="joomla3" prefix="j3m_"/> <server type="nginx" offset="UTC" tld="dev"/> <php version="5.4"/> <cache enabled="0" time="15" handler="file"/> <debug system="1" language="1"/> <meta description="Test installation" keywords="" showVersion="0" showTitle="1" showAuthor="1"/> <sef enabled="0" rewrite="0" suffix="0" unicode="0"/> <feeds limit="10" email="author"/> <session lifetime="15" handler="database"/> </environment>
name- The name for this environment. For the default environment, it is always
Common settings to all test servers are kept in an environment named
default and stored in
An average environment definition will contain just the server, joomla, and database elements.
Defines settings of the docker host.
dockyard- This setting determines the directory, where the the generated volumes (file systems) are located.
port- The port, on which the proxy is expected to listen.
Defines the Joomla version and the sample data.
version- This setting determines the Joomla version to be installed in this environment. It can be any Joomla version since 1.0.0. The version can be fully qualified, e.g., 3.4.2, but 3.4, 3, latest, master, staging, or any other branch name can also be used.
sampleData- Which sample data to install, if any. The file
sample_<value>.sqlmust exist for the selected Joomla version and database driver.
The hostname of the database server is determined by the selected driver. The corresponding container is automatically linked to the Joomla installation.
driver- This determines the type of the database being used by this Joomla installation. Currently, mysql, mysqli, pdomysql, and postgresql are supported.
name- The name of the database containing the Joomla site’s data tables.
prefix- The prefix applied to the name of the database tables used by this Joomla installation. For Joomla v1.5.x and v1.6.x this is “jos” by default, and should another Joomla site have to share the same database, the database tables would be kept separate by setting up this second site with a different prefix – e.g. “jos2”. With Joomla v1.7.x the same result is achieved by using a prefix that is a randomly generated alphabetic code and underscore – e.g. “vduea_”.
Define the server settings.
type- The engine to use. Valid values are nginx and apache.
offset- The time zone.
tld- The top level domain for the URL.
Define the PHP version.
version- The PHP version to use. Supported are all minor versions since PHP 5.4. Defaults to 'latest'.
Defines the Joomla! cache settings. These values are written to the
enabled- This setting controls whether or not site caching is enabled. When enabled, web pages are held for a period of time in cache storage and are retrieved from there rather than being re-created each time required.
handler- This setting defines the mechanism used to manage the cache storage.
time- This parameter defines the maximum time for which web pages are held in the cache storage before being updated with the current version. The default is 15 minutes.
Defines the Joomla! debug settings. These values are written to the
system- If set to “1”, Joomla will add debug information on every page, below the normal web page area. This information will include various forms of diagnostic information, including the full database queries used in generating the page. The default setting is “No”. The mix and format of diagnostic information presented by the debug function may be altered by editing the parameters of the Debug - System plug-in (Extensions > Plug-in Manager).
language- If set to “1”, Joomla will activate features designed to help debug language translations for a Joomla site. This includes the addition of language translation information to page debug information (requires system also set to “1”), and markers to show translated content within the web pages themselves. For further information, refer to Debugging a translation.
Defines the Joomla! meta settings. These values are written to the
description- Text added here appears in web page headers as the “description” metadata entry.
keywords- Words and phrases (separated by commas) added here appear in web page headers as the “keywords” metadata entry.
showVersion- Whether or not to expose the Joomla version in the metadata.
showTitle- (Only present in Joomla v1.6.x and later.) Appends the site name to page titles in the
titletag of each web page header. Joomla v1.6.x introduced this feature as an option to either include the site name text before the page title (e.g. Site Name – Page Name) or omit it. With Joomla v1.7.x the options also include inserting the site name after the page name (e.g. Page Name – Site Name) as well as before.
showAuthor- When this parameter is set to “1” an “author” metadata entry is added to the page header when appropriate, using the content item’s author name as the metadata text.
Defines the Joomla! SEF settings. These values are written to the
enabled- Joomla’s internal representation of URLs tends to be lengthy and also difficult to interpret by humans and search engine spiders. This is a typical example of the internal URL for a page displaying a content item: www.example.com/index.php?option=com_content&view=article&id=22&Itemid=437. If this option is set to “1”, the URL is modified into a shorter and more meaningful form: www.example.com/index.php/getting-started. The identifying text in the URL (in this case “getting_started”) is derived from the Alias text set up for each Category, content item, and Menu item.
rewrite- When this parameter is set to “1”, Joomla will use the mod_rewrite function of Apache web servers to eliminate the
index.phppart of the URL. Thus when this is operating the “search engine friendly” URL shown above will become: www.example.com/getting-started.
Note: This parameter is set to “0” by default. It should not be set to “1” unless the web server uses Apache software. The
htaccess.txtfile is automatically renamed to
suffix- When set to “1”, Joomla will add .html to the end of the most site URLs thus simulating static file-based web content. The URLs shown above will then become: www.example.com/index.php/getting-started.html or www.example.com/getting-started.html.
unicode- (Only present in Joomla v1.6.x and later.) When saving edited content, the former setting attempts to convert, where appropriate, any alias text into the corresponding Latin characters. When set to “1”, Joomla leaves any non-Latin characters in the alias text unchanged. Changing this parameter does not retroactively change aliases, it just changes the behaviour of automatic alias generation for future content editing and creation.
Defines the Joomla! feeds settings. These values are written to the
limit- The number of content items to be shown in any RSS newsfeeds set up on the web site. By default, this is set to 10, although unless the site is very active a smaller number may be better.
Defines the Joomla! session settings. These values are written to the
lifetime- This parameter determines how long a before user is automatically logged off for being inactive. The default setting is 15 minutes, although it can be useful to temporarily lengthen this parameter on development sites to avoid having to repeatedly log back in.
handler- Selects the mechanism used to hold session information between one page request and the next one from the same user. The options are “database” (the default) and “none”. The former stores session information as entries in a table in the site’s Joomla database, the latter uses the session handling mechanism built in to PHP.
Latest Joomla!2.5 on Apache with MySQLi and sample data
<environment name="j25-mysqli"> <joomla version="2.5" sampleData="data"/> <server type="apache"/> <database driver="mysqli" name="joomla25" prefix="j2m_"/> </environment>
Latest Joomla!3 on Nginx with PostgreSQL, no sample data
<environment name="j3-postgresql"> <joomla version="3"/> <server type="nginx"/> <database driver="postgresql" prefix="j3p_"/> </environment>
PRs are welcome. If you encounter any bug or issues, please use the issue tracker.
To contribute code or bugfixes, clone this repository, add your changes and make a pull request against the
On the command line, enter
within the project's root directory.
The main test creates a complete setup in the
dockyard directory, which can be used
to explore the possibilities. To invoke it, run
$ phpunit tests/DockerComposeGeneratorTest
This step is already included in the convenience command
composer build as described below.
For the Apache and PHP-FPM containers, this project provides own images (see
src/Service/docker). To ensure that those
images have the required traits, a separate suite of tests was created in
tests-container. They were separated
from the other tests, because they need 1-2 minutes for each container and PHP version to run.
The tests ensure that for each supported PHP version
- Containers build successfully and
- both FPM resp. Apache handler and CLI
- have the requested PHP version
- have a suitable Xdebug version enabled
- use catchmail instead of sendmail
- support OpenSSL
- support MysqlI and PDO Driver for MySQL
- support PostgreSQL and PDO Driver for PostgreSQL
To run these tests, enter
$ phpunit tests-container
on the command line.
composer scripts are provided to make life a bit easier. They are run from the project's root directory, and frees you from having to change into the
dockyard directory as required by
$ composer test
PHPUnit is run with the
--testdox option after removing
$ composer build
Starts the containers in the background after running the tests.
$ composer stop
Stops all running containers.
$ composer clean
Removes the containers and the
dockyard content. If necessary, the containers are stopped automatically.