Pivotal/tcserver
tcserver Installation
Contents |
Overview
https://content.pivotal.io/blog/part-one-comparing-apache-tomcat-and-pivotal-tc-server
Pivotal tc server builds on top of Apache Tomcat and adds a few key features:
- Enterprise support (with purchased license)
- Multi-instance support with shared binaries - individual runtime instances allows a separation between the binaries and the applications/configuration, allowing one set of binaries to power multiple instances.
- Variable substitution within server.xml - allows for consistent configuration and port management
Note: Pivotal tcserver 3.x is available through the pivotal repo, however to get the latest version, 4.x, you need to download and install the RPM from pivnet manually.
https://tcserver.docs.pivotal.io/4x/docs-tcserver/topics/whats-new-4.0.0.html#rpm-packaging
Installing tcserver 3.x - Linux
references: https://tcserver.docs.pivotal.io/3x/docs-tcserver/topics/install-getting-started.html
https://tcserver.docs.pivotal.io/4x/docs-tcserver/topics/tutwebapp.html
In this example we will be installing tcserver 3.x on a CentOS 7 vm using the pivotal repo.
Adding the Pivotal Repo and installing the package
Accept the EULA
~$ wget -q -O - http://packages.pivotal.io | sudo sh
Verify you see the new package
~$ sudo yum search pivotal-tc-server-standard
Install tcserver, ant, and java
~$ sudo yum install pivotal-tc-server-standard ant java-1.8.0-openjdk
Setting the user variables
To discover your Java home variable, you need to find the executable location and then use that to discover JAVA_HOME. You will need to omit /jre
if it appears in your java_home results.
~$ which java /bin/java ~$ /bin/java -XshowSettings:properties -version 2>&1 > /dev/null | grep 'java.home' java.home = /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64/jre
Ant HOME should always be /usr/share/ant
With both the JAVA_HOME
and ANT_HOME
found, we can set the following in our bash profile. Make sure to omit /jre
from your JAVA_HOME:
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64" export ANT_HOME="/usr/share/ant" export PATH=$PATH:$JAVA_HOME/bin
You can use the following to append the variables in your bash profile, make sure to update the variables to match your versions.
~$ echo -e export JAVA_HOME='"'/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64'"'"\n"export ANT_HOME='"'/usr/share/ant'"'"\n"export PATH='$PATH:$JAVA_HOME/bin' >> ~/.bash_profile
NOTE: I would set the user variables to both your sudo capable user AND the tcserver user.
tcserver user
When you installed tcserver, it created a user called tcserver
. We will want to replicate the steps above for setting the user variables for JAVA_HOME
and ANT_HOME
for this user, tcserver, as well. When you log in as tcserver
, you will want to use the -E
flag in order to maintain user variables.
~$ sudo -E su -l tcserver
If you forget to use the -E
flag, you can set the variables for your current session like this:
~$ source ~/.bash_profile
Testing with Hello World app
With tcserver installed and its dependencies configured, we can test it with a simple hello world java app.
Before we begin, lets log in as the user tcserver
~$ sudo -E su -l tcserver
git clone and ant build
tcserver recommends that all instances be placed in /var/opt/pivotal/pivotal-tc-server-standard
instead of the default executable directory.
~$ git clone https://github.com/carefreepineapple/hello-world-war.git
Now lets build the WAR file.
~$ cd ~/hello-world-war/ ~$ ant all
The important file we want from this is the WAR file, which will be located in the ./dist/
folder.
~$ ls ~/hello-world-war/dist/ hello.war
create instance, copy war, and start
To create a new instance, we need to use the tcruntime-instance.sh
script.
~$ /opt/pivotal/pivotal-tc-server-standard/tcruntime-instance.sh create hello-world-war -i /var/opt/pivotal/pivotal-tc-server-standard/
Now that we've created a new instance called hello-world-war, we can copy the WAR file we generated earlier into it.
~$ cp ~/hello-world-war/dist/hello.war /var/opt/pivotal/pivotal-tc-server-standard/hello-world-war/webapps/
Finally lets try to start the instance.
~$ /opt/pivotal/pivotal-tc-server-standard/tcruntime-ctl.sh hello-world-war start -i /var/opt/pivotal/pivotal-tc-server-standard/
firewalld
In case you need a quick reference on how to open the needed port(s) in firewalld
~$ sudo firewall-cmd --get-active-zone public interfaces: eth0 enp0s3 ~$ sudo firewall-cmd --zone=public --add-port=8080/tcp ~$ sudo firewall-cmd --zone=public --list-ports 22/tcp 8080/tcp
uninstall tcserver 3.x
In the event you want to remove tcserver 3.x, you can do the following:
~$ sudo yum erase pivotal-tc-server-standard
However, that will leave a few things
~$ sudo rm -rf /var/opt/pivotal/ sudo userdel -r tcserver
Installing tcserver 4.x - Linux
references: https://tcserver.docs.pivotal.io/3x/docs-tcserver/topics/install-getting-started.html
https://tcserver.docs.pivotal.io/4x/docs-tcserver/topics/tutwebapp.html
In this example we will be installing tcserver 4.x on a CentOS 7 vm using the pivotal RPM package.
Downloading and the RPM package
Easy way
There are (2) files that you need:
- pivotal tc server rpm
- pivotal tc server runtimes rpm
use a GUI browser > https://network.pivotal.io > login > download RPM for tcserver 4.x and runtime > SCP to your tcserver
Hard way
You can download the RPM directly if you utilize the pivnet UAA API token and get an access token to obtain the package.
UAA API Token
Go to https://network.pivotal.io > Edit Profile > UAA API Token > Copy the UAA API Token to your clipboard or temp file. This UAA API Token is good until you request a new token.
UAA API Token example: 2c97607c2fc14e9cac26de4ba0c10340-r
Obtain Access Token
With the UAA API Token, you can now obtain a short lived Access Token.
~$ curl -H "Accept: application/json" \ > -H "Content-Type: application/json" \ > -X POST \ > -d '{"refresh_token":"2c97607c2fc14e9cac26de4ba0c10340-r"}' \ > https://network.pivotal.io/api/v2/authentication/access_tokens {"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6InNoYTItMjAxNy0wMS0yMC1rZXkiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiI5ZmVmMzQ4ZDU0Y2M0ZmU2YTA5YmQ2MmQ3ZGViMzM5NiIsInN1YiI6IjE3ZGYyYTRmLTIzNjEtNGNiZS05ZTAwLTYzMGFiY2U5ODEyNiIsInNjb3BlIjpbIm9wZW5pZCJdLCJjbGllbnRfaWQiOiJwaXZuZXQtcHJvZHVjdGlvbiIsImNpZCI6InBpdm5ldC1wcm9kdWN0aW9uIiwiYXpwIjoicGl2bmV0LXByb2R1Y3Rpb24iLCJyZXZvY2FibGUiOnRydWUsImdyYW50X3R5cGUiOiJhdXRob3JpemF0aW9uX2NvZGUiLCJ1c2VyX2lkIjoiMTdkZjJhNGYtMjM2MS00Y2JlLTllMDAtNjMwYWJjZTk4MTI2Iiwib3JpZ2luIjoidWFhIiwidXNlcl9uYW1lIjoiZmdpdWxpYW5pQHBpdm90YWwuaW8iLCJlbWFpbCI6ImZnaXVsaWFuaUBwaXZvdGFsLmlvIiwicmV2X3NpZyI6ImUzYTc1NmY1IiwiaWF0IjoxNTM0MTg2NTc4LCJleHAiOjE1MzQxOTAxNzgsImlzcyI6Imh0dHBzOi8vdWFhLnJ1bi5waXZvdGFsLmlvL29hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwiYXVkIjpbInBpdm5ldC1wcm9kdWN0aW9uIiwib3BlbmlkIl19.BN3g9cNcLu5Yo5qX-lYpkUYUq7-xcNNJ3n7hdy4nefrX7ruGx6i6u_qoNMiF4fGgCbXu4xdaXix0Dvxvo1tOG0X_8Gh5uFgD6bVqRN1__r38gNfZTrYlYZIBWegKVm40IvHHHlT_GhK4A6jA7SM-aTfZ8Auwo6VrCvzHRgggdVUg8N2xz9ZyEzku1gtFZVLLqxcDpLEw9DZiVY8yFptQZd7DJjE66GZtNWO8zqT08NND7_6_CpE4uqtSjV-_FRih-aRGXLNKdMlSd6kGi_nmO4wNGn05mwzAzOgPlaeIkU0OMdqjw-Sj8g5fzgr_QzArVrVj1xkGWH5AuiIAyA50Vg"}
Test the access token. Using the -v
flag, you can see the 200 response from the server.
~$ curl -v -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InNoYTItMjAxNy0wMS0yMC1rZXkiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiI5ZmVmMzQ4ZDU0Y2M0ZmU2YTA5YmQ2MmQ3ZGViMzM5NiIsInN1YiI6IjE3ZGYyYTRmLTIzNjEtNGNiZS05ZTAwLTYzMGFiY2U5ODEyNiIsInNjb3BlIjpbIm9wZW5pZCJdLCJjbGllbnRfaWQiOiJwaXZuZXQtcHJvZHVjdGlvbiIsImNpZCI6InBpdm5ldC1wcm9kdWN0aW9uIiwiYXpwIjoicGl2bmV0LXByb2R1Y3Rpb24iLCJyZXZvY2FibGUiOnRydWUsImdyYW50X3R5cGUiOiJhdXRob3JpemF0aW9uX2NvZGUiLCJ1c2VyX2lkIjoiMTdkZjJhNGYtMjM2MS00Y2JlLTllMDAtNjMwYWJjZTk4MTI2Iiwib3JpZ2luIjoidWFhIiwidXNlcl9uYW1lIjoiZmdpdWxpYW5pQHBpdm90YWwuaW8iLCJlbWFpbCI6ImZnaXVsaWFuaUBwaXZvdGFsLmlvIiwicmV2X3NpZyI6ImUzYTc1NmY1IiwiaWF0IjoxNTM0MTg2NTc4LCJleHAiOjE1MzQxOTAxNzgsImlzcyI6Imh0dHBzOi8vdWFhLnJ1bi5waXZvdGFsLmlvL29hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwiYXVkIjpbInBpdm5ldC1wcm9kdWN0aW9uIiwib3BlbmlkIl19.BN3g9cNcLu5Yo5qX-lYpkUYUq7-xcNNJ3n7hdy4nefrX7ruGx6i6u_qoNMiF4fGgCbXu4xdaXix0Dvxvo1tOG0X_8Gh5uFgD6bVqRN1__r38gNfZTrYlYZIBWegKVm40IvHHHlT_GhK4A6jA7SM-aTfZ8Auwo6VrCvzHRgggdVUg8N2xz9ZyEzku1gtFZVLLqxcDpLEw9DZiVY8yFptQZd7DJjE66GZtNWO8zqT08NND7_6_CpE4uqtSjV-_FRih-aRGXLNKdMlSd6kGi_nmO4wNGn05mwzAzOgPlaeIkU0OMdqjw-Sj8g5fzgr_QzArVrVj1xkGWH5AuiIAyA50Vg" \ -X GET https://network.pivotal.io/api/v2/authentication ... < HTTP/1.1 200 OK
NOTE: The hard way method is still being researched and is not complete.
Installing the RPM packages
With the RPM packages on your host, we can install them
~$ sudo yum localinstall ./pivotal-tc-server-4.0.2-RELEASE.noarch.rpm ./pivotal-tc-runtime-9.0.10.A-RELEASE.noarch.rpm -y
Verify they are listed as installed
~$ sudo yum list | grep pivotal pivotal-tc-runtime-9.noarch 9.0.10.A-RELEASE installed pivotal-tc-server.noarch 4.0.2-RELEASE installed pivotal-tc-server-standard.noarch 3.2.11-RELEASE pivotal-app-suite
We also need to install a couple of dependencies.
~$ sudo yum install ant java-1.8.0-openjdk -y
Setting the user variables
To discover your Java home variable, you need to find the executable location and then use that to discover JAVA_HOME. You will need to omit /jre
if it appears in your java_home results.
~$ which java /bin/java ~$ /bin/java -XshowSettings:properties -version 2>&1 > /dev/null | grep 'java.home' java.home = /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64/jre
Ant HOME should always be /usr/share/ant
With both the JAVA_HOME
and ANT_HOME
found, we can set the following in our bash profile. Make sure to omit /jre
from your JAVA_HOME:
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64" export ANT_HOME="/usr/share/ant" export PATH=$PATH:$JAVA_HOME/bin
You can use the following to append the variables in your bash profile, make sure to update the variables to match your versions.
~$ echo -e export JAVA_HOME='"'/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64'"'"\n"export ANT_HOME='"'/usr/share/ant'"'"\n"export PATH='$PATH:$JAVA_HOME/bin' >> ~/.bash_profile
NOTE: set the user variables to your sudo capable user.
tcserver executable
If you want to set the tcserver
executable to accessible from any directory for your sudo capable user, also add this to the bash_profile
:
export PATH=$PATH:/opt/pivotal/tcserver/standard ~$ echo -e export PATH='$PATH:/opt/pivotal/tcserver/standard' >> ~/.bash_profile
tcserver user
When you installed tcserver, it created a user called tcserver
, however unlike 3.x, 4.x does NOT create a home directory for the tcserver
user.
When you log in as tcserver
, you will want to use the -E
flag in order to maintain user variables.
~$ sudo -E su -l tcserver
tcserver bash_profile
If you want to be able to run the tcserver
executable as the tcserver user without specifying the full path, you'll need to create a bash_profile for the tcserver
user. By default, tcserver is set to have a home directory of:
~$ cat /etc/passwd | grep tcserver tcserver:x:1001:995:tc Server User:/var/opt/pivotal/tcserver:/bin/bash
Copy the template .bash_profile
and update it
~$ sudo cp /etc/skel/.bash_profile /var/opt/pivotal/tcserver Add the following to the .bash_profile, make sure to update the paths export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64" export ANT_HOME="/usr/share/ant" export PATH=$PATH:$JAVA_HOME/bin export PATH=$PATH:/opt/pivotal/tcserver/standard or ~$ echo -e export JAVA_HOME='"'/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64'"'"\n"export ANT_HOME='"'/usr/share/ant'"'"\n"export PATH='$PATH:$JAVA_HOME/bin' "\n"export PATH='$PATH:/opt/pivotal/tcserver/standard' | sudo tee --append /var/opt/pivotal/tcserver/.bash_profile
Don't forget to set the permissions on the .bash_profile
if you used a sudo user to perform the above (2) commands.
~$ sudo chown tcserver:pivotal /var/opt/pivotal/tcserver/.bash_profile
tcserver.properties
New in 4.x, you can configure default values in the file, tcserver.properties
which is located:
${TCSERVER_HOME}/conf/tcserver.properties ie. /opt/pivotal/tcserver/standard/conf
Most of these values are populated with default values during installation, but some like JAVA_HOME are not. This is not needed if you already set your user environment variables up, but is still good practice to do.
~$ vim /opt/pivotal/tcserver/standard/conf/tcserver.properties java.home=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.181-3.b13.el7_5.x86_64
Testing with Hello World app
With tcserver installed and its dependencies configured, we can test it with a simple hello world java app.
Before we begin, lets log in as the user tcserver
~$ sudo -E su -l tcserver
git clone and ant build
tcserver recommends that all instances be placed in /var/opt/pivotal/tcserver/instances
instead of the default executable directory. With 4.x though, you do not need to worry about specifying this, it will automatically be done for you through the tcserver
executable.
~$ cd /tmp/ ~$ git clone https://github.com/carefreepineapple/hello-world-war.git
Now lets build the WAR file.
~$ cd /tmp/hello-world-war/ ~$ ant all
NOTE: You may need to update the file build.xml
with the tomcat bin location (referred to in the file as tcserver.home
. The tomcat bin location will be in the runtime files, ie: /opt/pivotal/tcserver/runtimes/tomcat-9.0.10.A.RELEASE
. You do not need to define bin in the path.
The important file we want from this is the WAR file, which will be located in the ./dist/
folder.
~$ ls /tmp/hello-world-war/dist/ hello.war
create instance, copy war, and start
To create a new instance, we need to use the tcserver
executable
~$ /opt/pivotal/tcserver/standard/tcserver create hello-world-war
Now that we've created a new instance called hello-world-war, we can copy the WAR file we generated earlier into it.
~$ cp /tmp/hello-world-war/dist/hello.war /var/opt/pivotal/tcserver/instances/hello-world-war/webapps/
Finally lets try to start the instance.
~$ /opt/pivotal/tcserver/standard/tcserver start hello-world-war
firewalld
In case you need a quick reference on how to open the needed port(s) in firewalld
~$ sudo firewall-cmd --get-active-zone public interfaces: eth0 enp0s3 ~$ sudo firewall-cmd --zone=public --add-port=8080/tcp ~$ sudo firewall-cmd --zone=public --list-ports 22/tcp 8080/tcp
uninstall tcserver 4.x
In the event you want to remove tcserver 3.x, you can do the following:
~$ sudo yum erase pivotal-tc-server.noarch pivotal-tc-runtime-9.noarch -y
However, that will leave a few things
~$ sudo rm -rf /var/opt/pivotal/ sudo userdel tcserver