Installing teamspace with Docker

With the Docker installation, Tomcat and Java run in the container, while MariaDB, the application and the userfiles remain on the host (see How teamspace is built). This guide was created under Debian; on other distributions, individual steps may differ.

The guide uses the name projectfacts. If you have teamspace, replace it.

1. Prepare the system

Create the user:

groupadd -g 161 projectfacts && useradd -r -u 161 -g projectfacts projectfacts

Required standard packages:

apt update && apt upgrade -y && apt install vim unzip htop libtcnative-1 bash-completion net-tools iptables-persistent -y

2. Install Docker

Install dependencies:

apt update && apt install apt-transport-https ca-certificates curl gnupg2 software-properties-common libxml-xpath-perl zip mariadb-server apache2 certbot

Install Docker from the repository:

apt install docker.io docker-compose

Alternatively, you can install Docker manually following the official Docker guide and Docker Compose following this guide.

3. Set up MariaDB

Database user: projectfacts or teamspace · Database name: as appropriate · Password: your choice · Host address: 172.17.0.%

Docker creates a 172.17.0.0/16 network. The database is reachable from the container at 172.17.0.1. For the database import you need a database template – contact us for it.

Create tmpfs

mkdir -p /var/log/mysql/tmp

To make the tmpfs reboot-proof, add it to /etc/fstab:

tmpfs   /var/log/mysql/tmp      tmpfs   defaults,size=3G        0       0

Mount and check:

mount -a

Then use df -h to check that the tmpfs directory is mounted.

Create innodb_tmpdir

mkdir -p /mnt/userfiles/tmp && chmod 1777 /mnt/userfiles/tmp

Adjust MariaDB

Import the time zone:

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

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

[mysqld]
bind-address = 0.0.0.0
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
innodb_tmpdir           = /mnt/userfiles/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

Restart MariaDB:

systemctl restart mariadb

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

4. Set up projectfacts/teamspace

From Tomcat version 9.0.92 onwards, projectfacts/teamspace must be updated to at least 2024.2.68 or 2024.1.72.

1. Create the following folders:
   • /srv/projectfacts
   • /srv/projectfacts/logs
   • /srv/projectfacts/logs/tomcat
   • /srv/projectfacts/webapp
   • /mnt/userfiles/<customer-name>
2. Copy the deploy-war-docker.sh and the projectfacts-20XX.X.XX.war to /srv/projectfacts and unpack:

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

   Check the paths in the deploy-war-docker.sh beforehand.
3. Copy the userfiles.tar.gz2 to /mnt/userfiles/<customer-name> and unpack it with tar -xf userfiles.tar.gz2.
4. Set the permissions for the log directory:

   chown projectfacts:projectfacts /srv/projectfacts/logs/tomcat/

Create the Dockerfile

Create /srv/projectfacts/Dockerfile – it is needed to build the image:

FROM tomcat:9-jdk17-temurin-focal

RUN groupadd -g 161 projectfacts && \
    useradd -r -u 161 -g projectfacts projectfacts && \
    rm -r /usr/local/tomcat/webapps && mkdir /usr/local/tomcat/webapps && \
    chown -R projectfacts:projectfacts "/usr/local/tomcat"

USER projectfacts

Build the image:

docker build -t projectfacts:jdk17 .

Adjust web.xml

Adjust the following values in /srv/projectfacts/webapp/WEB-INF/web.xml. For mail sending and receiving to work, timer.mailfetcher must not be 0 (value in seconds; 0 disables mail traffic):

<context-param>
   <param-name>timer.mailfetcher</param-name>
   <param-value>30</param-value>
</context-param>

Set mail.positive_mail_list to .* so that mail sending is not restricted:

<context-param>
   <param-name>mail.positive_mail_list</param-name>
   <param-value>.*</param-value>
</context-param>

Set server.url (and webdav.url) to your domain:

<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>

Under oauth2Gateway.url, specify the URL for the OAuth 2.0 redirect (for projectfacts https://www.projectfacts.de, for teamspace https://www.teamspace.de):

<context-param>
    <param-name>oauth2Gateway.url</param-name>
    <param-value>https://www.projectfacts.de</param-value>
</context-param>

You only enter the PDF processing service if you use it (see Setting up the PDF processing service):

<context-param>
    <param-name>pdfConvertService.url</param-name>
    <param-value></param-value>
</context-param>

Adjust context.xml

Open /srv/projectfacts/META-INF/context.xml and enter the user, password and database URL. Since Docker is used, 172.17.0.1 (the Docker network) must be entered as the host – the Tomcat reaches MariaDB through it:

username="projectfacts"
password="projectfacts"
url="jdbc:mysql://172.17.0.1:3306/projectfacts?useUnicode=true&useSSL=false&serverTimezone=Europe/Berlin"

Add the font (Jasper font)

Place the jasper-font-default-1.2.0.jar in /srv/projectfacts/webapp/WEB-INF/lib/.

5. Adjust iptables

To protect MariaDB from outside access, iptables rules are created; the Tomcat port 8080 is only allowed for localhost. Allow SSH first, otherwise you will lock yourself out of the server:

iptables -A INPUT -p tcp -m tcp --dport 22 -j ACCEPT
iptables -A INPUT -s 172.17.0.0/16 -p tcp -m tcp --dport 3306 -j ACCEPT
iptables -A INPUT -s 127.0.0.1/32 -p tcp -m tcp --dport 3306 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 3306 -j DROP
iptables-save > /etc/iptables/rules.v4

6. docker-compose.yml

Create a docker-compose.yml under /srv/projectfacts:

version: '2.3'

services:
        tomcat:
                container_name: "projectfacts"
                image: projectfacts:jdk17
                logging:
                    options:
                        max-file: "5"
                        max-size: "10m"
                volumes:
                        - "/srv/projectfacts/webapp:/usr/local/tomcat/webapps/ROOT"
                        - "/srv/projectfacts/logs/tomcat:/usr/local/tomcat/logs"
                        - "/mnt/userfiles/<customer-name>:/srv/projectfacts/userfiles"
                ports:
                        - "127.0.0.1:8080:8080"
                restart: unless-stopped
                cpus: 4
                stop_grace_period: 30s
                network_mode: bridge
                environment:
                        TZ: "Europe/Berlin"
                        CATALINA_OPTS: "-Djava.awt.headless=true -Xmx1024m -XX:ParallelGCThreads=2 -XX:ConcGCThreads=2"

• Adjust the path /mnt/userfiles/<customer-name> under volumes.
• Adjust TZ: "Europe/Berlin" to your time zone if necessary.
• You control the memory through -Xmx in CATALINA_OPTS.

Set the permissions for the log directory:

chown projectfacts:projectfacts /srv/projectfacts/logs/tomcat

Useful Docker commands

docker exec -it <container-name> /bin/bash   # enter the container
docker logs <container-name>                 # show logs
docker-compose up --no-start                # recreate the container without starting
docker-compose down                         # delete the container
docker rm <container>                        # alternatively: delete the container
docker-compose start                        # start
docker-compose stop                         # stop
docker-compose restart                      # restart
docker-compose stats                        # statistics
docker ps                                   # running containers
docker ps -a                                # all containers
docker images                               # show images
docker rmi <image>                          # delete an image

The docker-compose commands must always be run in the /srv/projectfacts folder.

7. Start the container for the first time

Change to /srv/projectfacts and start:

docker-compose up -d

8. Set up the reverse proxy

Finally, set up the web server: Apache or Nginx.

Common questions & needs

Related topics

• How teamspace is built Installation Concept
• Setting up Apache as a reverse proxy Installation Configuration
• Version-specific update notes Installation Reference