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.
Preparation
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
JVM
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.
Database
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
Configuration
Application
Download the application from the form on the website www.ametys.org/community.
- The Ametys Portail application can be found at https://www.ametys.org/community/en/telecharger/ametys -portail/ ametys-4 .html #tabs-4
- The Ametys ODF application can be found at https://www.ametys.org/community/en/telecharger/ametys -odf/ ametys-odf-4 .html #tabs-4
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
Data
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.
JVM
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'; FLUSH PRIVILEGES; exit
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/
Tomcat
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 server | Tomcat configuration for an HTTPS server Apache |
|---|---|
|
<Connector port="8080" proxyPort="80" URIEncoding="UTF-8" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" compression="on" compressableMimeType="text/html,text/xml, text/plain,text/javascript, application/javascript,text/css,application/json" compressionMinSize="2048" />
|
<Connector port="8082" proxyPort="443" scheme="https" secure="true" URIEncoding="UTF-8" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" compression="on" 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)
[Unit] Description=Apache Tomcat Web Application Container After=network.target [Service] Type=forking EnvironmentFile=/home/cms/Ametys_CMS/setenv-ametys.sh Environment=JAVA_HOME=/usr/lib/jvm/java-default Environment=CATALINA_PID=/opt/tomcat/current/temp/tomcat.pid Environment=CATALINA_HOME=/opt/tomcat/current Environment=CATALINA_BASE=/opt/tomcat/current Environment='UMASK=0022' ExecStart=/opt/tomcat/current/bin/startup.sh ExecStop=/opt/tomcat/current/bin/shutdown.sh User=cms Group=cms UMask=0022 RestartSec=10 Restart=always LimitNOFILE=20000 [Install] WantedBy=multi-user.target
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):
#!/bin/sh AMETYS_CMS_HOME="/home/cms/Ametys_CMS/ametys_cms_home" AMETYS_SITE_HOME="/home/cms/Ametys_CMS/ametys_site_home" export AMETYS_CMS_HOME export AMETYS_SITE_HOME
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 CATALINA_OPTS 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
Application
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:
- Back-office address: http://cms.mondomaine.com
- In the case of a single-server installation:
- Websites / Front-office IP addresses: 127.0.0.1
- Websites / Front-office applications: http: //localhost:8080
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 .
Configuration
The application directory must have the following structure:
- /home/cms/Ametys_CMS/application/site -> v1_0_0/site
Tomcat
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>
Apache
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 </IfModule>
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).
Performance
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" </IfModule>
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
Database
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).
Application
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
System
Remember to add sudoers via the visudo command for the tomcat site.
Solr
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.
Deployment
Application
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.
Data
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
#!/bin/sh SOLR_JAVA_HOME="/usr/lib/jvm/java-default" SOLR_JAVA_MEM="-Xmx1G -Xms1G" SOLR_HOME="/home/cms/Ametys_CMS/ametys_solr_home" SOLR_LOGS_DIR="/home/cms/Ametys_CMS/ametys_solr_home/logs" 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
SOLR_INSTALL_DIR="/home/cms/Ametys_CMS/application/solr" SOLR_ENV="/home/cms/Ametys_CMS/setenv-solr.sh" RUNAS="cms"
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
Launch
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):
[Unit] Description=Apache SOLR ConditionPathExists=/home/cms/Ametys_CMS/application/solr After=syslog.target network.target remote-fs.target nss-lookup.target systemd-journald-dev-log.socket Before=multi-user.target Conflicts=shutdown.target [Service] User=cms Group=cms LimitNOFILE=1048576 LimitNPROC=1048576 PIDFile=/home/cms/Ametys_CMS/ametys_solr_home/solr-8983.pid Environment=SOLR_INCLUDE=/home/cms/Ametys_CMS/setenv-solr.sh Environment=RUNAS=cms Environment=SOLR_INSTALL_DIR=/home/cms/Ametys_CMS/application/solr Restart=on-failure RestartSec=5 startLimitIntervalSec=60 ExecStart=/home/cms/Ametys_CMS/application/solr/bin/solr start -f ExecStop=/home/cms/Ametys_CMS/application/solr/bin/solr stop PrivateTmp=true Restart=on-failure [Install] WantedBy=multi-user.target
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