Operation

Introduction

This manual contains information on installation and maintenance operations (backups, updates, etc.) forAmetys ODF . It also contains a number of useful tips.

We recommend that you first read the installation manual(demo or serverversion ) for your application, to familiarize yourself with all the concepts described here. Please also read the additional installation manual for your project, if available, to learn about its specific features: in some cases, some of the information presented here may not be applicable.

Target audience

This manual has been written for people who wish to administer Ametys ODF , i.e. carry out maintenance operations such as backups, updates, etc...

Comments

If you need help, or if you'd like to share your suggestions, criticisms or praise, don't hesitate to ask for help on the forums. You can also help us improve this documentation by adding your own comments.

Data types

Ametys manages two types of data.

Main data (JCR)

The main data concerns content, metadata, attachments, page organization, workflow and so on. They are managed byAPI JCR 2.0 (JSR 238).
The Apache JackRabbit implementation(http://jackrabbit.apache.org) is used because physical storage can be achieved in different ways: file system, embedded database (DERBY), classic database (MySQL), ...
To find out about all the implementations and how to configure them, you can consult the site of JackRabbit.

The Repository configuration file JackRabbit is WEB-INF/param/repository.xml.

By default, Ametys uses Derby and the file system, all stored in the configured directory (see configuration page).

Secondary data (SQL)

Secondary data can be (depending on your application configuration) :

• the users
• user groups
• rights management
• ...

They are stored in a database SQL (MySQL for example). The chosen database is visible in the configuration parameters (see the configuration page).

Backup and Restore

Backup

To save data, it is necessary to save all data types simultaneously. The following steps are required:

• Stop the Tomcat server to ensure data consistency.
• Copy the 'data' directory containing the main data (the path to this directory is defined in the application configuration parameters).
• Dump the database containing the secondary data.
• Archive all data in one file.
• Delete old backups to conserve disk space.
• Restart the server Tomcat.

It is very important that everything is saved simultaneously, otherwise application inconsistencies may occur: it is therefore advisable to perform these operations when no user is logged in and no automatic work is in progress (by switching off tomcat , for example).

It's a good idea to make a backup every night, using a cron job for example.

Catering

To restore data, perform the following steps:

• Stop the server Tomcat.
• Unzip the backup file whose name is specified in the parameter.
• Copy this new directory into data.
• Import database dump.
• Restart the server Tomcat.

It is very important that everything is restored simultaneously, otherwise application inconsistencies may occur: it is therefore advisable to perform these operations when no user is logged in and no automatic jobs are running.

It is also advisable to make a backup just before the restore, in case the restoration goes badly.

Update

To update Ametys ODF , follow these steps:

• Installation of new versions of applications CMS and SITE
• Copy configuration and data files from previous version to new version
• Change from current version to new version.
• Restart services.

Other operations may also be required, depending on the update supplier's instructions: SQL scripts, for example (please refer to the Migration Manual).
Installation of a new instance of the application (without data) is immediately carried out with the most recent version, and does not require any update.

Before executing an update, it is important to check the available disk space. For a 70 MB application, for example, you need 150 MB of available space, because once the 70 MB file has been downloaded, it will be unzipped to form the application.

Downloaded zips and old versions are kept on disk: if after installing the new version you need to go back to the previous version, you need to shut down the services and switch the symbolic links back to the old directory.

It's rarely necessary to keep more than 2 old versions, so you can delete old directories (and zip files) to save disk space. Please note! Logs are not retained during an update.

Start / Restart

If you have followed our installation procedure, you need to use the corresponding services (Apache Tomcat , Apache HTTPD...) for example by running the command "/etc/init.d/tomcat start".

Otherwise, the start, stop and restart processes depend on your installation and servlet engine. For example, on Tomcatyou'll probably need to run the startup and shutdown scripts in the bin directory.

Sometimes, the shutdown call is not completed correctly. After a few seconds, check that the server has really stopped, by looking at the processes still running.

Cover

Cover for tomcat

You'll find the JavaScript and CSS files already served.

Empty the tomcat

Site cache

These are mainly pages generated by the CMS application to be served statically from the SITE application.

Empty site cache

System status check

Check the tomcat

Several tomcat may be running on the same machine. When the command is returned, you can see how many tomcat are running, as well as their "identity".
This command can be used to ensure that a stopped tomcat has actually stopped.

DNS check

Si un serveur http est configuré : wget <mon_url> et vérifier que la page a bien été écrite.
Il arrive parfois qu’un serveur ait des problèmes d’accès aux autres machines réseaux, cela permet de vérifier que les serveurs ont bien accès entre eux.

Logs

Application logs

Functional errors are generally contained in application logs. These logs are configured via the WEB-INF/log4j file .xml and stored in the WEB-INF/logs directory (see the log4j website for details).
They can be downloaded directly from the administration area (see the dedicated page in the administration manual for details).

System logs

Apache Tomcat errors are stored in the Tomcat/logs directory. The catalina.out file contains console information (including startup information). Tomcat also uses log4j.
These logs must be monitored and deleted regularly, so as not to fill up disk space.

In order to prevent a full disk, which could result from the regular growth of log files (tomcat, CMS...), we recommend deleting unnecessary log files. This operation is available from theadministrator area.

System resources

The ODF back-office and front-office applications are web applications JAVA.

Processor

Apart from special projects, Ametys ODF doesn't need a lot of CPU, but it can be interesting to use multiple processors and multi-heart.

Memory

The back-office can become memory-hungry depending on the number of users (should be between 512MB and 1GB for several users).
The front-office is not memory-hungry when it is mainly static: in this case, Tomcat is only used during searches or when generating other dynamic pages.

At startup, the -Xms and -Xmx options specify the minimum and maximum memory allocated. Sun's JVM takes the minimum space and, whenever necessary, increases the space without exceeding the maximum size; however, it never returns the memory to the system: so it's important to consider that this memory is not shareable. If you want to know how memory is actually used by the JVM, you can have a look at the administration area).

In the case of an OutOfMemoryException returned by Java, this can come from 2 types of memory:

• internal memory for loading classes allocated with the maxPermSize option. It depends on the number of libraries ( jar files) and java classes loaded. The more applications are used in Tomcat, the larger this memory needs to be. In general, 128 to 192MB is used.
• program memory (the memory we usually talk about). Generally speaking, 512MB to 2GB is used. Java doesn't know how to manage more than 32GB on 32-bit machines. Each user making a request to the server requires memory (which depends on the type of request): it is therefore impossible to predict the amount of space required; only our experience allows us to estimate the size. For example, 50 small requests will certainly use less memory than 10 large ones. It is possible to modify the number of simultaneous requests allowed on Tomcat, in order to solve certain problems. Waiting users will receive a server-busy message.

Example of memory settings

For more details on JVM configuration, please refer to the JDK6/Virtual Machine documentation.

Disk space

The disk space used by the entire system is difficult to predict. It consists of :

• system components (Tomcat, Apache...)
• of the application (about 70MB per version). So if you implement 5 updates, you'll use 70 * 5 * 2 (application size * number of updates * (cms + site)) + downloaded zip files. This can take up a lot of space. Older versions should be archived elsewhere.
• the JCR database, which requires a lot of disk space. In fact, it stores all successive versions of all content, so it's constantly growing. A typical website can easily take up 100MB of text alone (i.e. excluding images and attachments) for a single version of content. After the first few months of use (which are the most intensive), it's common to reach 500MB. Disk size must therefore be expandable. If the project manages videos, this must be taken into account when forecasting disk space.