3. Linux installation guide

If you haven't already done so, we recommend that you read the previous pages of the CMS Ametys installation guide, to get an overview of how it works and a better understanding of the technical installation. This guide assumes that you have some knowledge of system administration, that you understand the architecture ofAmetys and ideally that you have already installed a Java J2EE application with Apache/Tomcat/MySQL on a Linux server.

This guide corresponds to a typical installation that has been tested and validated on an Ubuntu 20.04/Debian 10 virtual machine. AsAmetys is presented in the form of completely standard Web applications, other installations will also work, particularly with regard to access paths, users, sub-domains, ...

This page describes the technical installation of the various applications (Back-Office, Front-Office, Solr) making up Ametys, as well as their software prerequisites. Please note that Front-Office installation is very similar to Back-Office installation. When using 2 virtual machines, it is possible to duplicate the Back-Office virtual machine to make it the Front-Office, with only one link and a few configuration elements differing (Apache and Ametys).

After installation, when you access Ametys for the first time, you must proceed to the configuration phase, described in the administration manual.

  1. Preparation
    1. User and domain names
      1. Back office
      2. Front-office (for two servers)
  2. Back-office (CMS)
    1. Installing prerequisites
      1. Apache HTTPD
      2. JVM
      3. Database
      4. Application server
    2. Configuration
      1. Application
      2. Data
      3. Apache HTTPD
      4. JVM
      5. Database (SQL)
      6. Tomcat
      7. Application
  3. Front-office (SITE)
    1. Installing prerequisites
    2. Configuration
      1. Tomcat
      2. Apache
      3. Activate vhost for front-end
      4. Database
      5. Application
      6. System
  4. Solr
    1. Deployment
      1. Application
      2. Data
    2. Launch
  5. End of installation



User and domain names

Back office

  • Create user 'cms' and group 'cms' (see system tips for creating a user)
  • Declare a DNS to the machine, e.g. cmstest.mondomaine.com or cms.mondomaine.com

Front-office (for two servers)

  • Create user 'cms' and group 'cms
  • Declare a DNS to the machine, for example wwwtest.mondomaine.com or www.mondomaine.com

Back-office (CMS)

Log in as cms user.

Some installations require the root user. It is advisable for the root user to then delegate to the cms user: access to configuration files, the right to restart tomcat...

As root, give runtime access to the cms directory

cd /home      
chmod 711 cms      

Installing prerequisites

All software installation required for Ametys must be carried out by the root user. Application launch management will then be delegated to the cms user.

Apache HTTPD

To communicate on port 80 (HTTP) and/or 443 (HTTPS), you need to install Apache HTTPD 2.

If you have installed Apache HTTPD 2 with the package available in your OS's default repository, it will be configured to launch automatically (see prerequisites section). If not, you may need to configure its automatic launch (see http://httpd.apache.org or your operating system documentation).

The following Apache modules must be installed and activated:

  • deflate
  • expires
  • headers
  • mod_proxy
  • mod_proxy_http
  • mod_rewrite
  • mod_deflate

Depending on your application, you may need additional modules.

Pour les activer, utiliser la commande a2enmod <nom_du_module>

a2enmod deflate expires headers proxy proxy_http rewrite deflate      

To use https, you'll need to install openssl via your OS's repository system.

To enable https, you'll need to add the following modules:

  • socache_shmcb
  • ssl
a2enmod socache_shmcb ssl     


To run the application, you'll need a 64-bit JRE or JDK 11.

 The JVM path will be referenced in scripts, so we recommend creating a symbolic link such as java_11 > jdk-11.0.10+9.


Only MySQL is documented, but installation with another DBMS takes place in the same way. Please refer to the manuals of the chosen DBMS to reproduce the necessary steps.

We strongly recommend that you do not use a Derby database in production for your data. You can, for example, install MySQL and configure its automatic launch (see http://www-fr.mysql.com/ or operating system documentation).

If you have installed MySQL with the package available in your OS's default repository, it will be configured to launch automatically (see prerequisites section). If not, you may need to configure its automatic launch (see http://www-fr.mysql.com/ or your operating system documentation).

On some distributions (e.g. Debian 10) you can install MariaDB instead of MySQL.

Application server

Only Tomcat is documented, but installation with another application server proceeds in the same way. Please refer to the manuals of the chosen application server to reproduce the necessary steps.

Next, we recommend you install Tomcat 9.x.

An earlier version will not support Java 11.

Tomcat must have the right to read and write in the back-office and front-office application directories. For example, you can "chown -R cms:cms" on the tomcat directory, or add the cms user to the group tomcat



Download the application from the form on the website www.ametys.org/community.

Be sure to select the Deployment Application tab - the other tabs correspond to automatic installation packages for demonstration purposes.

Transfer the archive provided by this form to your server in the /tmp directory, renaming it to "ametys.zip".
For example, if the version retrieved is "ametys-demo-4.3.12.zip", you'll need to run the following commands:

cd /tmp      
mv ametys-demo-4.3.12.zip ametys.zip 

We're going to create the application tree. This must never contain spaces!

The root directory is a subdirectory of the cms user directory: Ametys_CMS

We recommend that you create a symbolic link to the latest version of the cms directory.
When upgrading, simply create a new version directory and then change the symbolic link: in the event of a problem, you can switch back to the previous version.

cd /home/cms      
mkdir Ametys_CMS      
cd Ametys_CMS      
mkdir application      
cd application      
mkdir tmp      
mkdir v1_0_0      

#Déploiement de l'application      
cd /home/cms/Ametys_CMS/application/v1_0_0      
unzip /tmp/ametys.zip      

#Création d'un lien vers la version courante      
cd ..      
ln -sf v1_0_0/cms cms      

The zip file available on the website is composed of :

  • a directory CMS for the back office
  • a SITE directory for the front office


It is necessary to separate the data from the application, so that when updates are made, the data is directly accessible.

The data location is defined by the AMETYS_CMS_HOME environment variable, which is used by the application.

#Préparation du répertoires de données      
cd /home/cms/Ametys_CMS      
mkdir ametys_cms_home
#Variables d'environnement      
export AMETYS_CMS_HOME=/home/cms/Ametys_CMS/ametys_cms_home

Do the same for the front-office with the environment variable AMETYS_SITE_HOME to the folder /home/cms/Ametys_CMS/ametys_site_home.

Apache HTTPD

Use the apache2.conf configuration file to set up Apache Httpd.
In this file, you'll need to customize directory values (/home/cms/Ametys_CMS/application/cms), domain name (cms.mondomaine.com), port tomcat (8080), etc.
Don't forget to activate any necessary modules (such as mod_proxy* or mod_rewrite, for example): these are usually already declared but commented out.

Attachment: httpd-cms.conf

#En tant que root:      
cd /etc/apache2/sites-available      
cp /tmp/httpd-cms.conf /etc/apache2/sites-available/000-httpd-cms.conf      
#Modifier le fichier pour remplacer cms.mondomaine.com...      
cd /etc/apache2/sites-enabled      
#Si besoin supprimer les sites inutiles (par exemple le site par default 000-default.conf)      
#Créer un lien pour déclarer le cms      
ln -sf ../      
ln -sf ../sites-available/000-httpd-cms.conf      
#Vérifier le chemin vers les logs (en fin de fichier)      

Apache 2.4
The example httpd-cms.conf file is compatible with Apache 2.4.


If you're using CAS authentication and your certificate is not " trusted ", remember to import it into the JVM using the keytool.
The following example imports the certificate into the default keystore. If you wish, you can import it into a different keystore.

 keytool -import -file cas-dev.anyware.cer -keystore /path/to/jvm/jre/lib/security/cacerts -trustcacerts -storepass changeit      

Database (SQL)

Since Ametys 4.0, it is no longer necessary to initialize database tables, only to create databases and their users.

In our case, we will need to create three databases:

  • One is for CMS data (users, groups, forms, etc.).
  • The other to site data (users, groups, preferences, etc.)
  • The latest application monitoring

To these bases, we associate an "all-powerful" user. 

mysql -u root -p      
#Sous MySQL      
create database Ametys_CMS;      
grant all privileges on Ametys_CMS.* to ametys_user identified by 'ametys_pwd';      
grant all privileges on Ametys_CMS.* to 'ametys_user'@'localhost' identified by 'ametys_pwd';      

In this example, the login is ametys_user. The password used is ametys_pwd: "identified by 'ametys_pwd';". We advise you to use another login and password.

If you're using a remote database, you'll also need to assign rights to the IP or domain of CMS. You may need to adapt the configuration of Mysql (or Maria DB) to allow external connections. Before using Ametys, run a command-line test from the Ametys server.

A database connector is required, depending on the choice of database (MySQL, Oracle, Derby, PostgreSQL). This connector must be copied into the lib directory of the application (back-office and front-office)
For MySQL :

MySQL connector for Java

wget -O /tmp/mysql-connector.tar.gz https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.23.tar.gz
cd /tmp/      
tar xzf mysql-connector.tar.gz      
cp mysql-connector-java-8.0.23/mysql-connector-java-8.0.23.jar /home/cms/Ametys_CMS/application/cms/WEB-INF/lib/      
cp mysql-connector-java-8.0.23/mysql-connector-java-8.0.23.jar /home/cms/Ametys_CMS/application/site/WEB-INF/lib/      


By default, Tomcat comes with a number of potentially useless applications. We recommend that you delete them using the following instructions.

We advise you to deploy tomcat in the /opt/tomcat/ folder and make a symbolic link from the version to the current folder.

#En tant que root      
cd /opt/tomcat/current/webapps      
rm -rf *      

Configure tomcat by editing the /path/to/ file tomcat/conf/server. xml

example file supporting all configurations,
You'll need to comment the Services according to your configurations. This example file is configured for http proxy apache on localhost with ports: BO http on 8080, BO https on 8082, FO http on 8081 and FO https on 8083. All you need to do is adapt the proxies on your apache vhosts to suit your needs.

At the beginning of the file, select a free port on the machine: this port is used internally by tomcat .

vi /opt/tomcat/current/conf/server.xml      
 <Server port="8005" ...      

In the middle of the file, select another free port on the machine: this port will be used to access tomcat. On this same line, add the instruction "proxyPort="80"", used to link to Apache HTTPD, or "proxyPort="443 scheme="https"" for a Apache https server. Also on this line, add the instruction "URIEncoding="UTF-8"", which indicates the default encoding to be used when processing requests. To enhance performance, text files (pages, CSS and javascript files) can be compressed.

Tomcat configuration for a Apache HTTP serverTomcat configuration for an HTTPS server Apache


<Connector port="8080"
compressableMimeType="text/html,text/xml, text/plain,text/javascript, application/javascript,text/css,application/json"
compressionMinSize="2048" />




<Connector port="8082"
compressableMimeType="text/html,text/xml, text/plain,text/javascript, application/javascript,text/css,application/json"
compressionMinSize="2048" />      



Remember to check that the other connectors are commented :

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"      
maxThreads="150" scheme="https" secure="true"      
clientAuth="false" sslProtocol="TLS" />      
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />      

All that remains is to adapt the Host tag to your configuration.

Next, prepare the application directory and declare the :

mkdir -p /opt/tomcat/current/conf/CatalinaBO/localhost
vim ROOT.xml      

In the file, edit the following content by customizing the paths:

<Context docBase="/home/cms/Ametys_CMS/application/cms" privileged="true" antiResourceLocking="false"></Context>      

If you have installed Tomcat with the package available in your OS's default repository, it will be configured to launch automatically (see prerequisites section). If not, you may need to configure its automatic launch (see http://tomcat.apache.org or your operating system documentation).

To configure tomcat with systemd:

vi /etc/systemd/system/tomcat.service
systemctl daemon-reload

Example of a service file configuration (to be adapted to your configurations)

Description=Apache Tomcat Web Application Container

Example of a setenv-ametys.sh configuration file to position the AMETYS_*_HOME folders (as a cms user, in the /home/cms/Ametys_CMS folder):

CATALINA_OPTS="-Xmx5G -Xms512m -server"
JAVA_OPTS="-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dderby.stream.error.file=/home/cms/Ametys_CMS/ametys_cms_home/logs/derby.log -Duser.country=FR -Duser.language=fr -Dcom.sun.jndi.ldap.connect.pool.protocol='plain ssl' -Dcom.sun.jndi.ldap.connect.pool.timeout=6000 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/home/cms/Ametys_CMS/ametys_cms_home/logs/heapdump.log -XX:ErrorFile=/home/cms/Ametys_CMS/ametys_cms_home/logs/java_error%p.log"
export JAVA_OPTS

You can start and stop the server with the following commands (these commands must be run as root):

service tomcat start
service tomcat start

cms user rights to launch apache and tomcat with a sudo, create a file /etc/sudoers.d/cms-sudoers (adapt to your security requirements)

%cms ALL=NOPASSWD: /etc/init.d/apache2, /bin/systemctl * tomcat, /usr/sbin/service tomcat*, /bin/systemctl * solr, /usr/sbin/service solr*, /sbin/ifconfig

In this way, Tomcat can be launched as a cms with the command:

sudo service tomcat start      


Le paramétrage applicatif est réalisé via une interface dédiée, pour cela http://<webapps_cms>/_admin (login/mot de passe par défaut: admin/admin).

We invite you to use our online documentation: Administration manual

For more details, see data storage in the operating manual.

In general we have the following values:


Front-office (SITE)

The back-office application must be running correctly before you can start installing the front-office application.

Installing prerequisites

Installation of the front office is similar to that of the back office:

  • If using separate machines, install Apache HTTPD and the JVM, then configure them.
  • Install and configure Tomcat .


The application directory must have the following structure:

  • /home/cms/Ametys_CMS/application/site -> v1_0_0/site


Configure tomcat in the same way as for the back office, except that the host will be localhost in order to serve all sites via the same webapps.

To do this, you need to edit the file used to configure access to the application (you can use the example file proposed for the back-office and comment on the BO Service section):

 vi /opt/tomcat/current/conf/server.xml      

If you have several Tomcat on the same machine, make sure that the ports used are different.

Add the corresponding ROOT.xml file

mkdir -p /opt/tomcat/current/conf/CatalinaFO/localhost
vi ROOT.xml      
<Context docBase="/home/cms/Ametys_CMS/application/site" privileged="true" antiResourceLocking="false"></Context>          


These operations must be performed as root.

For the front-office application, the following Apache modules must be installed and activated:

  • mod_proxy
  • mod_proxy_http
  • mod_rewrite
  • mod_deflate
  • mod_expires
  • mod_unique_id
  • mod_headers

If you use the same Apache for both back-office and front-office, remember to add the missing modules.

To use https, you'll need to install openssl via your OS's repository system.

To enable https, you'll need to add the following modules:

  • socache_shmcb
  • ssl
a2enmod socache_shmcb ssl     

As with the CMS configuration, use the attached configuration file to set up Apache Httpd for the site application (this is an example to be adapted to your environment).
In this file, you need to customize:

  • directory values (/home/cms/Ametys_CMS/application, /home/cms/Ametys_CMS/ametys_site_home/cache),
  • domain name ($domain by www.mondomaine.com),
  • port number tomcat (8083 for your tomcat port),
  • site name ($siteid by your site ID)
  • skin the name of the skin ($skin by the name of theametys folder for this site)

A new Virtual Host must be declared for each site. 

Attachment: httpd-site.conf

Error pages
Error pages are managed by the site so that they are available when CMS is unavailable. This means that error pages must be defined specifically for each graphic charter.
In the Apache site rules, the mime module must be activated and languages added:

LoadModule mime_module modules/mod_mime.so      

<IfModule mime_module>      
    AddHandler type-map var      
    AddLanguage fr .fr      
    AddLanguage en .en      
    DefaultLanguage fr      

Then redirect the 404 error to the correct URL, the same for the other errors:

ProxyErrorOverride On      
ErrorDocument 404 /error/404.html      

And redirect the error and its resources to the corresponding files :

RewriteRule    ^/error/(.+)$  /home/cms/Ametys_CMS/application/site/skins/MASKIN/error/$1 [L]] ]>

Remember to replace MASKIN with the name of your graphic charter. If your site changes its graphic identity, you'll also need to modify the httpd-site.conf file.

If you wish to manage errors on the CMS side, simply comment on these lines.

If you wish to activate cache usage statistics, lines containing AMETYS_PROXY_PASS must not be deleted or modified (do not modify the LogFormat).

On the other hand, if you know that you won't be using this feature, you can adapt these configuration lines if required (in particular, the LogFormat can be adapted or deleted).


Each time a page is served, even if it and its resources are fully cached, the browser will run a series of requests anyway to make sure it has the latest version of CSS, images, or JS.

In order to achieve a much faster impression for the end user, it is possible to configure Apache so that it tells the browser that any CSS loaded is valid for 20 minutes: in this way, when browsing from page to page, all common graphic resources will never be reloaded.

On the other hand, if you modify your graphic charter, a visitor may continue to use old versions of images, js and CSS for some time: if this is something you do frequently, you may not need to implement this optimization, or you may need to reduce the validation time to just a few minutes.

To implement the optimization, you need to load the expires module (once only)

LoadModule expires_module      

and the following instructions (at the root, or for each virtualhost) (this is an example to be adapted to your needs)

<IfModule expires_module>      
  ExpiresActive On      
  ExpiresDefault "access plus 1 seconds"      
  ExpiresByType text/html "access plus 1 seconds"      
  ExpiresByType image/gif "access plus 20 minutes"      
  ExpiresByType image/jpeg "access plus 20 minutes"      
  ExpiresByType image/png "access plus 20 minutes"      
  ExpiresByType text/css "access plus 20 minutes"      
  ExpiresByType text/javascript "access plus 20 minutes"      
  ExpiresByType application/x-javascript "access plus 20 minutes"      
  ExpiresByType application/javascript "access plus 20 minutes"      
  ExpiresByType text/xml "access plus 20 minutes"      

Activate vhost for front-end

#En tant que root:      
cd /etc/apache2/sites-available      
cp /tmp/httpd-cms.conf /etc/apache2/sites-available/001-httpd-site.conf      
#Modifier le fichier pour remplacer cms.mondomaine.com...      
cd /etc/apache2/sites-enabled      
#Si besoin supprimer les sites inutiles (par exemple le site par default 000-default.conf)      
#Créer un lien pour déclarer le cms      
ln -sf ../      
ln -sf ../sites-available/001-httpd-site.conf      


As with the back-office application, you don't need to create the tables to initialize the database; you need to have created the database(s) with its associated user(s).


Restart Apache and Tomcat :

#Création d'un lien vers la version courante      
cd /home/cms/Ametys_CMS/application      
ln -sf v1_0_0/site site      


Il reste à configurer l’application site de la même manière que l’application CMS : http://<webapps_site>/_admin.

We invite you to use the online documentation: Page Create a new site / Site configuration section

In general we have the following values:

  • URL du CMS : http://<nom de domaine>:8080
    Valeur utilisée en accès interne par l'application


Remember to add sudoers via the visudo command for the tomcat site.



Ametys requires a single instance of SOLR. We recommend that you install SOLR on the back-office server and configure communications between Ametys Back-office and SOLR via localhost.



Download the version of SOLR corresponding to the version ofAmetys you are using: http: //releases.ametys.org/releases/org.ametys/ solr-app/. 

Déployez cette version dans /home/cms/Ametys_CMS/application/<numéro de version> (en tant qu'utilisateur cms)

Créez un lien symbolique /home/cms/Ametys_CMS/application/solr -> <numéro de version>/solr afin de pouvoir en changer facilement.


In the same way as data, indexing must be separated from the application and from Solr, so that when updates are made, it is not necessary to restart a complete indexing (as long as the model has not changed).

The location of indexing data is defined in the SOLR_HOME environment variable.

#Création du répertoire d'indexation /home/cms/Ametys_CMS/ametys_solr_home
cd /home/cms/Ametys_CMS      
mkdir ametys_solr_home      

Here's an example of an environment configuration file for SOLR (to be adapted to your configuration).

vi setenv-solr.sh
SOLR_OPTS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=$SOLR_LOGS_DIR/heapdump.log -XX:ErrorFile=$SOLR_LOGS_DIR/java_error%p.log"
SOLR_TIMEZONE=`date '+%Z'`

Check that these files are executable for the cms user:

  • /home/cms/Ametys_CMS/setenv-solr.sh
  • /home/cms/Ametys_CMS/application/solr/bin/solr

Configure the SOLR environment and the runtime user:

vi /home/cms/Ametys_CMS/application/solr/bin/init.d/solr

Creating symbolic links :

  • /home/cms/Ametys_CMS/ametys_solr_home/solr.xml -> /home/cms/Ametys_CMS/application/solr/server/solr/solr.xml
  • /home/cms/Ametys_CMS/ametys_solr_home/configsets -> /home/cms/Ametys_CMS/application/solr/server/solr/configsets


Solr should preferably be started before the back office.

Here's an example of a configuration file (to be adapted to your configuration) to run SOLR as a systemd service (/etc/systemd/system/solr.service):

Description=Apache SOLR
After=syslog.target network.target remote-fs.target nss-lookup.target systemd-journald-dev-log.socket



ExecStart=/home/cms/Ametys_CMS/application/solr/bin/solr start -f
ExecStop=/home/cms/Ametys_CMS/application/solr/bin/solr stop


Reload the systemd services. 

Adapt ulimit to meet the requirements of SOLR (for the cms account, if you have created one, user who launches solr or tomcat)

vi /etc/security/limits.conf
cms hard nofile 65535
cms soft nofile 65535
cms hard nproc 65535
cms soft nproc 65535

End of installation

Installation is now complete. 

We invite you to take a look at theAmetys technical operating guide, which contains details of application maintenance operations and various operating tips.


Back to top

Installation and operation manual