= Setup of a Cinnamon Server on Debian 9.8.0 (stretch)
> This documentation relates to Debian 9.8.0 Server (without GUI).[[br]]Particularly, it relates to a minimal Debian server VM installed from the Debian repositories on the KVM virtualization host.[[br]]The installation according to this documentation has been tested on a system of this type.

== Installing Cinnamon Server
* Log in to the standard Debian 9.8.0 VM (this is a minimal installation with {{{ssh}}} as the only option).
> **IMPORTANT:** Choose a safe password on production systems (see [#ref1 (1)]).
* Use the {{{su}}} command to acquire root privileges.
* Install Java (JDK), cURL and some other useful or required tools.
 {{{
 apt-get install default-jdk curl sudo less daemontools rsync davfs2 htop zip unzip sshpass
 }}}
* Create a new group and user for tomcat.
 {{{
 groupadd tomcat
 useradd -s /bin/false -g tomcat -d /opt/tomcat tomcat
 mkdir /opt/tomcat
 }}}
 * The home directory of this account is set to {{{/opt/tomcat}}}.
 * The shell of this account is set to {{{/bin/false}}}, so logging on is not possible.
* Download and extract tomcat.
 {{{
 cd /tmp 
 curl -O https://archive.apache.org/dist/tomcat/tomcat-8/v8.5.38/bin/apache-tomcat-8.5.38.tar.gz
 tar xzvf apache-tomcat-8.5.38.tar.gz -C /opt/tomcat --strip-components=1
 chgrp -R tomcat /opt/tomcat
 cd /opt/tomcat
 chown -R tomcat webapps/ work/ temp/ logs/
 chmod -R g+r conf
 chmod g+x conf
 chmod -R g+rw logs
 }}}
* Create a Tomcat service.
 * Create the service file.
  {{{
  nano /etc/systemd/system/tomcat.service
  }}}
 * Paste the following code into the file:
  {{{
  [Unit]
  Description=Apache Tomcat Web Application Container
  After=network.target

  [Service]
  Type=forking

  Environment=JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-amd64/jre
  Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
  Environment=CATALINA_HOME=/opt/tomcat
  Environment=CATALINA_BASE=/opt/tomcat
  Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'

  ExecStart=/opt/tomcat/bin/startup.sh
  ExecStop=/opt/tomcat/bin/shutdown.sh

  User=tomcat
  Group=tomcat
  UMask=0007
  RestartSec=10
  Restart=always

  [Install]
  WantedBy=multi-user.target
  }}}
 * Save and close the file.
* Start and test Tomcat.
 {{{
 systemctl daemon-reload
 systemctl start tomcat
 systemctl status tomcat
 }}}
 Alternatively, you can use the following syntax to control the tomcat service:
 {{{
 service tomcat start
 service tomcat stop
 service tomcat status
 }}}
* Stop tomcat.
 {{{
 service tomcat stop
 }}}
* Install PostgreSQL database.
 {{{
 apt-get install postgresql
 }}}
* Set password for user {{{postgres}}}.
> **NOTE:** This is required for backup and restore.
 {{{
 sudo -u postgres psql template1
 ALTER USER postgres PASSWORD 'myPassword';
 \q
 }}}
* Create a database user {{{cinnamon}}}.
 * Start the user creation program.
  {{{
  sudo -u postgres createuser --interactive
  }}}
 * Answer the questions as follows:
||=**Question** =||=**Answer** =||
||Enter the name of the role to add: ||{{{cinnamon}}} ||
||Shall the new role be a superuser? ||{{{n}}} ||
||Shall the new role be allowed to create databases? ||{{{n}}} ||
||Shall the new role be allowed to create more new roles? ||{{{n}}} ||
 * Set a password for the user.
 > **IMPORTANT:** Choose a safe password on production systems (see [#ref1 (1)]).
  {{{
  sudo -u postgres psql
  ALTER USER "cinnamon" WITH PASSWORD 'new_password';
  \q
  }}}
* Assign password to user cinnamon and add it to the tomcat group.
> **IMPORTANT:** Choose a safe password on production systems (see [#ref1 (1)]).
 {{{
 useradd -g tomcat -d /opt/cinnamon cinnamon
 passwd cinnamon
 mkdir /opt/cinnamon
 }}}
* Create a file {{{/opt/tomcat/bin/setenv.sh}}} and paste the following content into it:
 {{{
 export CATALINA_OPTS="$CATALINA_OPTS -Xms32m"
 export CATALINA_OPTS="$CATALINA_OPTS -Xmx4g"
 export CATALINA_OPTS="$CATALINA_OPTS -XX:MaxPermSize=256m"
 export CATALINA_OPTS="$CATALINA_OPTS -XX:MaxGCPauseMillis=750"
 export CATALINA_OPTS="$CATALINA_OPTS -XX:GCTimeRatio=9"
 export CATALINA_OPTS="$CATALINA_OPTS -server"
 export CATALINA_OPTS="$CATALINA_OPTS -XX:+DisableExplicitGC"
 export CINNAMON_HOME_DIR="/opt/cinnamon/cinnamon-system"
 }}}
* Set the permissions to the file {{{/opt/tomcat/setenv.sh}}}.
 {{{
 chmod ug+x /opt/tomcat/bin/setenv.sh
 }}}
* Pull files from the proxy to the VM.
> **NOTE:** This is specific to the texolution hosting environment. In other environments, the files must be provided in an appropriate way. A download package for the resources needed to install Cinnamon Server will be provided soon.
 {{{
 scp install@<proxy ip>:/home/install/content.sql.gz /root
 scp install@<proxy ip>:/home/install/content.tar.gz /root 
 scp install@<proxy ip>:/home/install/cinnamon.war /root
 gunzip /root/content.sql.gz
 }}}
* Restore the content files.
 {{{
 mkdir /opt/cinnamon/cinnamon-data
 mkdir /opt/cinnamon/cinnamon-data/index
 tar xf /root/content.tar.gz -C /opt/cinnamon/cinnamon-data
 }}}
* Move the {{{content}}} folder directly under {{{cinnamon-data}}}.
* Create database and import SQL dump.
 {{{
 sudo -u postgres psql template1
 create database content with owner=cinnamon;
 \q
 sudo -u postgres psql content < /root/content.sql 
 }}}
* Restore the configuration files.
 {{{
 mkdir /opt/cinnamon/cinnamon-system
 mkdir /opt/cinnamon/cinnamon-system/global
 mkdir /opt/cinnamon/cinnamon-system/global/log
 mkdir /opt/cinnamon/cinnamon-backup
 }}}
* Change the owner and permissions of the Cinnamon directories.
 {{{
 cd /opt/cinnamon
 chown -R cinnamon:tomcat cinnamon-data
 chown -R cinnamon:tomcat cinnamon-system
 chown -R cinnamon:tomcat cinnamon-backup
 chmod -R 770 cinnamon-data
 chmod -R 770 cinnamon-system
 chmod -R 770 cinnamon-backup
 }}}
* Flag all objects and folders in the repository to be indexed.
 {{{
 sudo -u cinnamon psql -d content
 insert into index_jobs select id,false,'cinnamon.ObjectSystemData',id from objects;
 insert into index_jobs select id,false,'cinnamon.Folder',id from folders;
 \q
 }}}
* Move {{{cinnamon.war}}}
 {{{
 mv /root/cinnamon.war /opt/tomcat/webapps
 }}}
* Set Tomcat service to start automatically.
 {{{
 systemctl enable tomcat
 }}}
* Start Tomcat.
 {{{
 service tomcat start
 }}}

== Installing Cinnamon Asynchronous Engine (CAE)
* Create a new group and user for CAE.
 {{{
 groupadd cae
 useradd -s /bin/bash -g cae -d /opt/cae cae
 mkdir /opt/cae
 }}}
 * The home directory of this account is set to {{{/opt/cae}}}.
 * The shell of this account is set to {{{/bin/bash}}}. For debugging purposes, it is useful to log on as the CAE user and run CAE from the shell.
 * Optionally, the shell can be set to {{{/bin/false}}}, disabling login as CAE user. Instead, testing can be performed as root.
* Unzip the file {{{cae.zip}}} to {{{/opt/cae}}}.
* Install dependencies, particularly mono from their repository (instead of the Debian packages).
 {{{
 apt-get install apt-transport-https dirmngr gnupg ca-certificates
 apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
 echo "deb https://download.mono-project.com/repo/debian stable-stretch main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
 apt update
 apt-get install mono-complete ca-certificates-mono imagemagick
 }}}
* Configure CAE.
 * Edit the configuration file.
  {{{
  nano /opt/cae/bin/CinnamonAsynchronousEngine.config.xml
  }}}
 * Set the user credentials.
 > **NOTE:** Details will follow.
* Transfer folder structure to user {{{cae}}}.
 {{{
 chgrp -R cae /opt/cae
 chown -R cae /opt/cae
 chmod -R 770 /opt/cae
 }}}
* Set owner and permission to script.
 {{{
 chgrp cae /opt/cae/bin/cae.sh
 chown cae /opt/cae/bin/cae.sh
 chmod a+x /opt/cae/bin/cae.sh
 }}}
* Set the script to be automatically started, and restarted when it exits (for any reason).
 * Copy {{{cae.sh}}} to {{{run}}}.
  {{{
  cp /opt/cae/bin/cae.sh /opt/cae/bin/run
  }}}
 * Create the {{{crontab}}}.
  {{{
  crontab -e
  }}}
 * Append the following code at the end of the crontab.
 > 120 seconds sleep time is on the safe side. On most systems, much shorter times work safely, e. g. 30 seconds. If the sleep time is too short, the process may fail to start correctly, so do not configure this value too small.
  {{{
  @reboot sleep 120; supervise /opt/cae/bin
  }}}
 * Save and close the file.

== Backup
Cinnamon itself does not contain a backup mechanism, since all data is contained in the PostgreSQL database and the content files. Both can be backed up with operation system or database standard means.

The backup configuration in detail depends on the system environment and the available backup target.

A sample configuration, using {{{rsync}}} to copy the content and the standard database dump utility to backup the database can be found in reference [#ref2 (2)]. The configuration described there is successfully used in several production systems and has the advantage to avoid huge content transfer every night due to the differential {{{rsync}}} function.

== References

* [=#ref1 (1)] [wiki:Public/Docs/SafePasswords Safe passwords]
* [=#ref2 (2)] [wiki:Public/Docs/CinnamonBackupRestore Backup and restore of a Cinnamon repository]