Version 3 (modified by iolaneandrade, 4 semanas atrás) (diff)


ATENÇÃO: Fora de uso

Operating Instructions

1. Terms of Reference

This report concerns the announcement number 46, "OBJ-REL - Layer Object-Relational Persistence ", published between days 04 to May 11, 2008 to be carried out from maio/2008 to October/2008.

2. Introduction

Under the terms of reference described in this project, the frameworks used by Interlegis allow the storage of information in both relational databases (PostgreSQL and MySQL) and in object databases (ZODB).

In general, when it is to represent information inside of Plone (using the Archetypes framework), the storage of data is usually in the object oriented (OO) database for ZODB objects. There are some solutions from Interlegis, such as the SAPL (System Support Legislative Process), which can be considered "Hybrid" solutions, storing information in different models (from information in relational database and share in database oriented to objects). However, the SAPL does not use the Archetypes framework and, in turn, not is related to this project.

This report address considerations relevant only to the first case, the mapping object-relational information. In this case, the information that would normally be stored in data banks OO must be mapped to a relational database. This third report complements the report 1 and 2 has previously delivered and concerns the delivery of the "instruction manual". Subsequently, the report 4 deal about last delivery, referring to the procedures of transfer of technology for Interlegis.

3. Instruction Manual

As described in Report 2, the solution of object-relational mapping implemented given the name of interlegis.sqlalchemystorage and is dependence on the main module archetypes.sqlalchemystorage. The installation of complete solution, and its configuration, is not a trivial process. In this sense, tried to follow the best practices for packaging modules Python, using buildout and virtualenv so that the process was simplified. The installation process is described in detail below.

4. Installation

The first step is to check the installed version of python interpreter. Installing the python interpreter version 2.4.4 have been made from packages, or when done manually, the support should include the library "zlib" (and, therefore, just at the time of compiling the package is installed zlib-dev or your equivalent).

To perform the installation from packages. "Deb", we can use the command below (for convention, commands preceded by # to be run as root or through sudo and commands preceded by $ may be performed by a common user):

# apt-get install python2.4 python2.4-dev python2.4-imaging python2.4-mysqldb build-essential

The packages and python2.4-imaging python2.4-mysqldb can also be installed via buildout, but it was found that the automatic procedure fails to some versions of the Ubuntu distribution and can be useful to keep the lines for installation of MySQLdb PIL and commented on the buildout and is apparently easier to use the standard distribution package. The package build-essential, then, is necessary for the compilation of Zope (which has parts of your code in C and need the gcc compiler and the make). To test whether the python2.4 is installed correctly and the python2.4 - python2.4-imaging and mysqldb, invoke the interpreter and trying to import the modules related:

$ python2.4
>>> import PIL
>>> import MySQLdb

With the python interpreter version 2.4 installed, must install and easy install virtualenv. For this, it is recommended to use the following commands:

# wget
# python2.4
# easy_install-2.4 virtualenv

If the python2.4 or easy_install-2.4 are not included in the variable PATH environment, it should add them (this is usually only necessary when the python interpreter is installed manually). This can be done by adding the following line at the end of /etc/profile

export PATH = /PATH_TO_PYTHON/bin/:$PATH

The PATH_TO_PYTHON usually is /usr/local.

To continue, you must create the base directory of the installation. This process is conducted with the support of a "checkout" the buildout, made from a repository SVN, followed by the creation of a virtual environment "virtualenv, installation of "ZopeSkel?" and implementing the "buildout". Therefore, the use of following commands:

$ svn co
$ virtualenv interlegis-plone25
$cd interlegis-plone25
$./bin/easy_install ZopeSkel
$ mkdir-p parts /instance/va/fss_storage parts/ instance/var/fss_backup

To load the source from the SVN repository via EXTERNALS.txt, use the following commands.

$cd src; svn up; cd ..

The file src / EXTERNALS.txt sets from which the repository framework interlegis.sqlalchemystorage and their main dependencies, the module archetypes.sqlalchemystorage are updated. When any correction implemented or improved, the update is only to repeat the commands above and restart the instance of Zope.

# Create this file: svn propget svn: externals. > EXTERNALS.txt
# Apply this file: svn propset svn: externals-F EXTERNALS.txt.
archetypes.sqlalchemystorage /branches/weimar-improvements
interlegis.sqlalchemystorage / trunk

It is perceived in the configuration file above that part of the "buildout" developed referring to the module is stored in a interlegis.sqlalchemystorage private SVN repository (, but the module archetypes.sqlalchemystorage is stored in the repository of the official framework Archetypes (

During the development of the project it became clear that many changes would be needed in module archetypes.sqlalchemystorage and therefore the same fairs were in a specific branch. The repository is public but with access to "writing" restricted. Moreover, the repository has restricted both for writing and for reading, but it is the Interlegis decide where you kept the source code produced, the repository in question was used for simple convenience. The Interlegis determine whether the products developed will be kept on servers or even the very Interlegis released publicly in the repository "collective" of Plone.

5. Configuration of MySQL

Before starting the Zope you must start the MySQL server, creating 'the banks of data and production testing with the appropriate permissions. Each Plone site can be a connection to a database different. There is also a definition of default connection used by the automated tests (described as doctests). For convention, the databases for testing and production adopted the use respectively the of following connection strings:

  • Development: "mysql://interlegis:interlegis@localhost/testinterlegis"
  • Production: "mysql://interlegis:interlegis@localhost/ID_PLONE_SITE"

In production, each Plone site can have a different database, where the name the database is the id of the object Plone Site. This connection string pattern may be amended in a property in the tool portal_properties/site_properties. Thus, if we consider that the id of a Plone Site in production would be "Interlegis," we have:

$ mysql-u root-p
Enter password:
Welcome to the MySQL monitor. Commands end with; or \ g.
Your MySQL connection id is 1
Server version: 5.0.51a-3ubuntu5.1 (Ubuntu)
Type 'help,' or '\ h' for help. Type '\ c' to clear the buffer.
mysql> create database interlegis;
Query OK, 1 row affected (0.12 sec)
mysql> create database testinterlegis;
Query OK, 1 row affected (0.00 sec)
mysql> grant all on interlegis.* to interlegis@localhost identified by 'interlegis';
Query OK, 0 rows affected (0.00 sec)
mysql> grant all on testinterlegis.* to Interlegis @ localhost identified by 'interlegis';
Query OK, 0 rows affected (0.00 sec)
mysql> flush privileges;

After adjusting the permissions of the database, it is important to check if the engine pattern of persistent MySQL is InnoDB. This engine allows the creation of tables with transactional support, with the use of "rollback." For this, it is recommended that the file /etc/mysql/my.cnf contains:

default-storage_engine = InnoDB

6. Configuration of Zope

After setting the permissions and the standard engine on the server for persistence MySQL, we can try to start the Zope server. For this, we can start the Zope in the "foreground" with the following command:

$./bin/instance fg

If during the first attempt to start the Zope instance of the following error occurs:

/opt/zope/interlegis-plone25/parts/instance/bin/runzope-X debug-mode = on
2008-10-15 12:50:58 INFO ZServer HTTP server started at Wed Oct 15 12:50:58 2008
Port: 8090
2008-10-15 12:50:58 CRITICAL Zope A user was not specified to setuid to; fix this to start the
root (change the effective-user directive in zope.conf)
Traceback (most recent call last):
   File "/ opt/zope/interlegis-plone25/parts/zope2/lib/python/Zope2/Startup/", line 56, in?  run ()
   File "/ opt/zope/interlegis-plone25/parts/zope2/lib/python/Zope2/Startup/", line 21, run in starter.prepare ()
   File "/ opt/zope/interlegis-plone25/parts/zope2/lib/python/Zope2/Startup/", line 94, in prepare self.dropPrivileges ()
   File "/ opt/zope/interlegis-plone25/parts/zope2/lib/python/Zope2/Startup/", line 213, in dropPrivileges return dropPrivileges (self.cfg)
   File "/ opt/zope/interlegis-plone25/parts/zope2/lib/python/Zope2/Startup/", line 382, in dropPrivileges raise ZConfig.ConfigurationError (msg)
ZConfig.ConfigurationError: The user was not specified to setuid to; fix this to start the root
(change the effective-user directive in zope.conf)

This means that the body can not be initialized with the user (usually the root or another user who has no write permission in the directory parts/instance/var). To fix this, you can change the policy of effective user - etc/zope.conf or make adjustments in permissions using the chmod command.

7. Testing

To run the automated tests that cover the implementation, interrupt the running instance of Zope (pressing ctrl-c is if it is running in foreground mode or using "$./bin/instance stop" if it is running in background) and then editing the configuration

file as shown below:

$vim src/interlegis.sqlalchemystorage/interlegis/sqlalchemystorage/


And then run the automated tests:

./bin/instance test-p "interlegis.sqlalchemystorage"

During the execution of the tests no error or failure should be reported. If this occurs, it is possible that the support of the MySQL InnoDB engine is not working and, in turn, the transactional integrity of the Zope and MySQL being affected.

To re-run using the Zope database of production, should be change the file to:

CLEAN_DB = False

8. Restart Zope

After running the automated tests and see that everything works as expected, can start the Zope server (with the command "$ ./bin/instance stop), open a browser and access the following address:

url: http://SERVER:8090/manage User: admin Password: admin

The port 8090 as well as the username and password "admin" are defined as standard by buildout.


The contents and data of this website are published under license:
Creative Commons 4.0 Brasil - Atribuir Fonte - Compartilhar Igual.