The Roma install on tei-c.org Martin Holmes 2015-12-29 freely available Born-digital document During the fall of 2015, Martin Holmes and Ian Rifkin worked on deploying a new version of Roma with a minor bugfix on tei-c.org, and formalized a previously rather ad-hoc setup so that future bugfixes and updates might be less mysterious. This document explains how the current setup works, and how to deploy an updated version of Roma. Where is Roma on tei-c.org? Roma, a helpful but rather outdated front end which enables people to create customized ODD files and schemas in a GUI interface, is available for public use here: http://www.tei-c.org/Roma/ If you click on "Start" to enter the process, you will see that the footer of the page shows detailed information about the current Roma version as well as the version of P5 it is using. If you have permission to log into the tei-c server, you will find it quite difficult to locate the actual running versions of Roma; they are (for largely historical reasons) located in /var/www/vhosts/tei-c.org/opencms_tomcat/usr/share In that directory, you will find multiple versions of the Roma codebase, in folders named for their versions: tei-roma-4.15 tei-roma-4.18 Each of these versions is working and available on a special URL based on its version number: http://www.tei-c.org/Roma-4.15/ http://www.tei-c.org/Roma-4.18/ In addition, there is a symbolic link, which at the time of writing points thus: tei-roma -> tei-roma-4.18 This means that the current "live" version is 4.18. How to deploy a new version Although Roma is not currently in active development, from time to time, bugfixes may be made and new versions deployed. This is how to do that: Fix bugs on the GitHub repository. Check out a fresh version from the GitHub repo into a folder in the deployment location, naming the folder based on the version number of the new version: /var/www/vhosts/tei-c.org/opencms_tomcat/usr/share/tei-roma-4.20 Test the new version thoroughly using its version-based URL: http://www.tei-c.org/Roma-4.20/ which will be available automatically through the Apache configuration. When you are confident that it's working correctly, ask the server administrator (currently Ian Rifkin) to update the symbolic link so that it becomes the current live version. (You may be able to do this yourself.) Configuration of Roma to run on tei-c.org The configuration of Roma is controlled by a number of files: VERSION, which contains the Roma version number. When doing a bugfix, don't forget to update this file. roma/config.php, which has all the URLs pointing to OxGarage and the eXist XML database required for Roma to function, as well as some local paths. It is recommended that you copy the config.php from the previous live version of Roma into a new deployment, and then just make a couple of required tweaks (such as changing the release date and the version number). roma/templates/main.tem. Due to a bug, this file must also be updated to provide the date of the roma release, in order for the correct date to appear in the footer of pages. What does Roma depend on? Roma does not do a great deal of real work itself. Instead, it requires a number of resources and services in order to work; these are apparent in the configuration file: define ( 'roma_xquery_server', 'http://www.tei-c.org/Query/' ); Roma uses the P5 Subset file retrieved via an XQuery call to the eXist XML database running on tei-c.org as a source of information on the modules, classes, elements and attributes available in the current release version of P5. That's why the eXist XML database must be updated as part of a P5 release. define ( 'roma_teiweb_server', 'http://www.tei-c.org/release/doc/tei-p5-doc/' ); In other operations such as adding elements and attributes to a schema, it retrieves information from the current live version of TEI P5 on the tei-c server. define ( 'oxgarage_server', 'http://www.tei-c.org/ege-webservice'); Finally, in order to transform an ODD file into a schema or into documentation, it calls on the web service provided by OxGarage. In order for Roma to function correctly, all these services have to be updated to matching versions, including (in the case of OxGarage) the latest version of the Stylesheets.