Skip to content

Instantly share code, notes, and snippets.

@drmalex07

drmalex07/README-tomcat-as-systemd-service.md

Last active October 22, 2025 22:03
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save drmalex07/e6e99dad070a78d5dab24ff3ae032ed1 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save drmalex07/e6e99dad070a78d5dab24ff3ae032ed1 to your computer and use it in GitHub Desktop.
Download ZIP
An example configuration for Tomcat as systemd service. #tomcat #systemd #systemd.service
Raw
README-tomcat-as-systemd-service.md

README

Let Tomcat is download and installed under /opt/tomcat. Also, let tomcat be a non-provileged user under which the server will be running.

We assume that we keep server's binaries under /opt/tomcat and we will create a server instance named foo under /var/tomcat/ (carrying its own conf, logs, webapps, work, lib directories). See also https://dzone.com/articles/running-multiple-tomcat.

Create a template service unit file at /etc/systemd/system/[email protected]:

[Unit]
Description=Tomcat - instance %i
After=syslog.target network.target

[Service]
Type=forking

User=tomcat
Group=tomcat

WorkingDirectory=/var/tomcat/%i

Environment="JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/"
Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom"

Environment="CATALINA_PID=/var/tomcat/%i/run/tomcat.pid"
Environment="CATALINA_BASE=/var/tomcat/%i/"
Environment="CATALINA_HOME=/opt/tomcat/"
Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"

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

#RestartSec=10
#Restart=always

[Install]
WantedBy=multi-user.target

Now, we can instantiate a service instance for our foo tomcat instance:

systemctl daemon-reload
systemctl enable [email protected]
systemctl start [email protected]
@Enigo
Copy link

Enigo commented Aug 3, 2023

Just wanted to draw your attention to this systemd issue, in particular this part:

don't use ExecStop= at all, just handle SIGTERM properly

Keeping ExecStop= directive in your tomcat systemd unit might lead to some issues.
For example, if your web service relies on some shutdown hooks to be executed on tomcat shutdown those won't be executed reliaby!

if you really want to keep the directive then do as @alparslanu6347 suggested ExecStop=/bin/kill -15 $MAINPID altho I think it is the same (or similar) way systemd is doing it by default anyways

@NickJH
Copy link

NickJH commented Sep 21, 2023

https://jdebp.eu/FGA/systemd-house-of-horror/tomcat.html

This is an excellent link and at the bottom gives a great way of avoiding Type=forking. Use a service file like:

# Tomcat systemd service file

[Unit]
Description=Tomcat Server
After=network.target

[Install]
WantedBy=multi-user.target

[Service]
Environment="CATALINA_BASE=/opt/tomcat-your_site"
WorkingDirectory=/opt/tomcat-your_site
User=tomcat
Group=tomcat
PermissionsStartOnly=true
ExecStart=/opt/tomcat-9.0.79/bin/catalina.sh run

Obviously adjust to suit your own environment. I need the WorkingDirectory for some apps to add their log files (so not the standard tomcat log files) to the logs folder. Many won't need it.
There is no need to set a CATALINA_HOME as the catalina.sh works it out from the path in the ExecStart statement.
I do not set JAVA_HOME here, preferring setenv.sh. This allows the instantiated version of the start up to run different versions of Java for different CATALINA_BASEs. Even if you do set it here, it can be overridden in setenv.sh.
PermissionsStartOnly is probably totally unnecessary.
It can be simply instantiated by changing the two references tomcat-your_site to tomcat-%I

If you want a pid file, add:

RuntimeDirectoryMode=755
RuntimeDirectoryPreserve=true
Environment=CATALINA_PID=/run/tomcat/tomcat-your_site.pid

Again, it can be instantiated.

@NickJH
Copy link

NickJH commented Nov 6, 2023 •
edited
Loading

Addendum.

There is a problem using the ExecStart=/opt/tomcat-9.0.79/bin/catalina.sh run method to start tomcat.

The problem is that the run method outputs to stdout and stderr. It you use catalina.sh start instead, stdout and stderr get redirected to your catalina.out file by the startup script. Using startup.sh calls catalina.sh start so it behaves the same. This redirect does not happen with the run method and so you get no catalina.out file. It is possible to play around with the systemd unit file options StandardOutput=journal, StandardError=inherit and SyslogIdentifier=??? to output to the journal, but then you have to trap the messages in the journal using an rsyslogd configlet (if you use rsyslog) and this becomes more of a pain if you have multiple tomcats and you want multiple catalina.out log files one per tomcat ......... and then its permissions don't follow the tomcats etc.

Bottom line - don't use the run method to start your tomcat with systemd.

@v-bulynkin
Copy link

v-bulynkin commented Oct 22, 2025 •
edited
Loading

Systemd also allows to make unprivileged user's services, very convenient. No need to use sudo, etc.

# Create or edit service. You shouldn't execute "daemon-reload" after systemctl edit command
systemctl edit tomcat --user --full --force

Paste something like this:

[Unit]
Description=Tomcat
After=network.target

[Service]
# The "exec" type is better than "simple"
Type=exec
EnvironmentFile=-/etc/default/tomcat
SyslogIdentifier=tomcat
ExecStart=/usr/bin/java $JAVA_OPTS $CATALINA_OPTS org.apache.catalina.startup.Bootstrap start
ExecStop=/usr/bin/java $JAVA_OPTS org.apache.catalina.startup.Bootstrap stop
Restart=on-failure

[Install]
# For user's services, write "default.target", not "multi-user.target"
WantedBy=default.target

Exec type
default.target

By default, user's services work only when the user is logged-in. To allow user services working independently from logon, turn on lingering:

# It needs to be done only once
loginctl enable-linger $USER

# Check status (Linger: yes)
loginctl user-status

To control such services, add --user parameter to systemctl.

# Start and enable service
systemctl --user enable --now tomcat

# Status
systemctl --user status tomcat

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment