Installing teamspace on Linux

This guide takes you through a complete Linux installation of projectfacts/teamspace under Debian/Ubuntu. Most steps require root access. You then set up the reverse proxy (Apache or Nginx) in a separate article.

The guide consistently uses the name projectfacts. If you have teamspace, replace the name accordingly. The paths may differ on existing installations.

1. Install packages

Install the required software (root access required):

apt update && apt upgrade -y && apt install mariadb-server tomcat10 openjdk-17-jdk-headless vim apache2 unzip htop libtcnative-1 bash-completion net-tools -y

2. Links and paths

3. Installation

1. Create the following folders:
   • /srv/projectfacts
   • /srv/projectfacts/logs
   • /srv/projectfacts/webapp
   • /srv/projectfacts/userfiles
   • /srv/projectfacts/jasper-font
2. Copy the deploy-war.sh and the projectfacts.war into the /srv/projectfacts directory.
3. Make the script executable and run it – this unpacks the .war:

   chmod +x deploy-war.sh
   ./deploy-war.sh

4. Copy the file userfiles.tar.gz2 to /srv/projectfacts/userfiles and unpack it:

   tar -xf userfiles.tar.gz2

Check the path to projectfacts in deploy-war.sh. You can adjust it through the BASEDIR variable. If the Tomcat runs under a user other than tomcat10, also adjust the chown in the script.

4. Adjust web.xml

Open the web.xml and adjust the paths to match your installation:

vim /srv/projectfacts/webapp/WEB-INF/web.xml

<context-param>
  <param-name>path.htdocs.directory</param-name>
  <param-value>/srv/projectfacts/webapp/htdocs/</param-value>
</context-param>
<context-param>
  <param-name>path.data.directory</param-name>
  <param-value>/srv/projectfacts/webapp/WEB-INF/data/</param-value>
</context-param>
<context-param>
  <param-name>timer.mailfetcher</param-name>
  <param-value>30</param-value>
</context-param>
<context-param>
  <param-name>mail.positive_mail_list</param-name>
  <param-value>.*</param-value>
</context-param>
<context-param>
  <param-name>server.url</param-name>
  <param-value>https://projectfacts.mycompany.de</param-value>
</context-param>
<context-param>
  <param-name>webdav.url</param-name>
  <param-value>https://projectfacts.mycompany.de</param-value>
</context-param>

• timer.mailfetcher specifies, in seconds, how often mail is fetched/sent (here every 30 seconds). A value of 0 disables mail traffic.
• mail.positive_mail_list with the value .* allows sending to all email addresses.
• Set server.url and webdav.url to your domain.

5. Configure MariaDB/MySQL

Database user: projectfacts · Database name: projectfacts · Password: your choice. The user needs full access to the database.

Import the time zones first – otherwise the MySQL server will not start:

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

Create the file /etc/mysql/mariadb.conf.d/51-projectfacts.cnf:

[mysqld]
bind-address = 127.0.0.1
skip-name-resolve

# projectfacts optimisations
default-time-zone       = Europe/Berlin
lower_case_table_names  = 1
innodb_buffer_pool_size = 1G
max_heap_table_size     = 512M
tmp_table_size          = 512M
innodb_log_file_size    = 256M
group_concat_max_len    = 4096
character-set-server    = utf8mb4
collation-server        = utf8mb4_unicode_ci
#tmpdir                  = /var/log/mysql/tmp

sql_mode = 'STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION'

# Optimisation for MariaDB 10.4+
#optimizer_switch        = 'rowid_filter=off'
#query_cache_size        = 0
#query_cache_type        = 0

Then restart the MariaDB/MySQL server.

The time zone of the database must match the operating system on which the Tomcat runs. On Linux, check it with cat /etc/timezone.

Import the database

Contact us for a template of the database structure if you do not yet have a dump.

Adjust context.xml

For the database connection to be established, copy the file webapp/META-INF/context.xml to tomcat10/conf/Catalina/localhost/ROOT.xml. The directory is created automatically the first time the Tomcat starts. In the copied file, adjust docBase, username, password and url.

6. Configure Tomcat

From Tomcat version 9.0.92 onwards, your projectfacts/teamspace must be updated to at least 2024.2.68 or 2024.1.72, otherwise you will receive an error message.

Adjust the file /etc/tomcat10/server.xml:

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="off" />
[…]
<Host name="localhost" appBase="webapps" unpackWARs="false" autoDeploy="false">

To give the Tomcat more memory, edit /etc/defaults/tomcat10:

JAVA_OPTS="-Djava.awt.headless=true -Xmx2048m"

Nightly Tomcat restart

Log in as root, enter crontab -e and add the following line (a daily restart at 04:00):

00 4 * * * systemctl restart tomcat10 >/dev/null 2>&1

Tomcat 10 read-only filesystem fix

This problem occurs when the Tomcat is installed from the repository of the following systems: Ubuntu 18.04 and later, Debian 9 and later.

1. Create the folder and the override file:

   mkdir /etc/systemd/system/tomcat10.service.d/ && vim /etc/systemd/system/tomcat10.service.d/override.conf

2. Insert the following content and save:

   [Service]
   ReadWritePaths=/srv/projectfacts/userfiles/

3. Reload the daemon and start the Tomcat:

   systemctl daemon-reload
   systemctl restart tomcat10

Add the font (Jasper font)

1. Download the jasper-font-default-1.2.0.jar from teamspace-classic.de and place it in /srv/projectfacts/jasper-font/.
2. Create a symlink:

   ln -s /srv/projectfacts/jasper-font/jasper-font-default-1.2.0.jar /usr/share/tomcat10/lib/jasper-font-default-1.2.0.jar

3. Restart the Tomcat.

Adjustment for PDF

So that PDF generation runs cleanly, comment out one line in the Java accessibility configuration:

vim /etc/java-17-openjdk/accessibility.properties

Comment out the following line and save:

#assistive_technologies=org.GNOME.Accessibility.AtkWrapper

Then restart the Tomcat.

Adjust permissions

chown -R tomcat10:tomcat10 /srv/projectfacts /srv/projectfacts/userfiles
systemctl start tomcat10.service

7. projectfacts update

Create a backup before every update. Only one .war file may ever be present, and a downgrade is not permitted.

1. Download the current projectfacts-x.x.xx.war from teamspace-classic (» Main folder → Current version → READ THE UPDATE NOTES! «) and observe the version notes.
2. Copy the file to /srv/projectfacts/.
3. Stop the Tomcat and check that it has really stopped:

   systemctl stop tomcat10

4. Run the deploy script in the projectfacts directory:

   ./deploy-war.sh

5. Start the Tomcat again:

   systemctl start tomcat10

6. Check in the projectfacts.log (at /var/log/tomcat/projectfacts.log) whether the update was successful, and then remove the .war from /srv/projectfacts/.

The complete procedure, including update notifications, is described in Performing an update.

Common questions & needs

Related topics

• Setting up Apache as a reverse proxy Installation Configuration
• Setting up Nginx as a reverse proxy Installation Configuration
• How teamspace is built Installation Concept