Being a VMware/SpringSource project, STS comes with tc Server as a servlet container. There’s a server definition out of the box, but if you want to create your own, it is IMHO less than obvious how to do that. There’s no documentation specific to tc Server that I could find. And it seems to me that it would be even less obvious to someone that didn’t work for SpringSource and use tc Server all the time. So I thought I’d just walk through my understanding of the process, using my current setup (STS 2.9.1 on Fedora).
First, a few notes about tc Server:
- For our purposes, it’s basically repackaged Tomcat. The supported package is a little more complicated, but to a developer, it’s not.
- It used to be SpringSource tc Server. Since the acquisition and re-branding, it’s VMware vFabric tc Server (making it a little harder to find in the dialog below).
- Since version 2.5 (the first re-branded version) it includes both Tomcat 6 and Tomcat 7. You can use either or both in the same installation. In fact, it’s possible to have more than one version of Tomcat 6 or 7 if you’ve upgraded an earlier installation of tc Server, but in this environment that’s probably uncommon.
- tc Server provides the means to define many server instances from one installation. Each has a separate instance directory (CATALINA_BASE) but refers to a shared installation CATALINA_HOME. This can be helpful if you want to try your application on multiple versions, clustered instances, with/without Spring Insight, etc.
It will likely be helpful for you to peruse the documentation on creating a tc Server instance if you’re not already familiar.
So with that in mind, let’s see what it’s like to “define a new server”, which is to say, a new server instance.
Despite what this shows, STS 2.9.1 doesn’t come with versions 2.0, 2.1, or the older 6.0 of tc Server – it comes with the ability to use them, but you’ll have to download, unpack, and define them yourself if you want them (and the “Download additional server adapters” link won’t help you, that’s for getting more server *types*, i.e. a completely different container like Glassfish). You have to open up the VMware folder to find the existing version, which is tc Server 2.6 under STS 2.9.1. (BTW, how about that Cloud Foundry plugin, eh? Need to check that out soon.)
- “Server’s hostname” needs to be some variation of “localhost” – can be the hostname of your workstation, or any of its IP addresses. There’s no ability to use a remote server. This is basically just for when STS brings up a browser for something you’ve deployed – no other real purpose that I can see.
- “Server name” is for you – this will show up in the “Servers” view so you’ll probably want something a lot shorter than the default, like “tcs2.6-t6”.
- “Server runtime environment” – ah, now here is where it gets interesting. A “runtime environment” is basically just a pointer to the tc Server installation and version of Tomcat within to be used – that’s all. When you define a runtime environment you don’t actually have a server instance yet, just a specification that you’ll use later for one. If no runtime environment is defined for the server type you’re trying to add, the first thing STS walks you through is creating a runtime environment, so that can be confusing if you don’t know the difference between a “runtime environment” and “server instance”.
STS comes with one runtime environment defined for the included tc Server 2.6 and Tomcat 7. If you want to use the Tomcat 6 runtime, you have to create it yourself. Let’s click the “Add…” link and walk through that.
- As always, you have to pick a “Name” for the runtime environment. This isn’t really going to show up anywhere except in the previous dialog.
- The “Installation directory” refers to where tc Server is installed (not the instance you want to use!). In this case, I’m using the one that came with STS.
- “Version” is the Tomcat version within that installation. I’m choosing 6, here. The initial one has Tomcat 7.
Once you click “Finish” the definition is available in the previous dialog for creating new server instances. If you select it and click “Next” we come to the instance specification dialog:
This is referring to the instance directory created under tc Server, which your server in STS will use. You probably want to create a new instance here, unless you’ve already created one from the command line and want to use that.
- The “name” in this case is actually functional… it will be the directory under the tc Server installation where the instance gets created.
- You have the option to specify one or more templates to add extra options to the basic configuration. In fact, the dialog won’t let you proceed without selecting one, so if you don’t know otherwise, just select the “base” template. You’ll get that anyway no matter what you choose, and you’ll also get a “bio” connector if you don’t specify any other connector template. The most likely other template of interest is “insight” which adds in Spring Insight to the configuration for profiling your app. This is pretty useful but also uses a lot of memory.
- “Layout” here gives you the option to use the “Separate” layout, which is basically what tc Server is all about – separating your instance definition from the CATALINA_HOME. I have no idea why you would use “Combined”.
You can click “Finish” here – the extra dialog from “Next” just gives you the ability to add apps (AKA “modules”) to the server, which you can do at your leisure later.
Where is the config? Where are the logs? Where are the apps?
Having set up your server, you may wonder how to tinker with it. There are a few surprises in store.
Here are a few places that by default don’t help much with understanding your server configuration:
- The tc Server instance you created. Whatever got created here, including whatever template definitions were added, is used as the original basis for your server, nothing more.
- The server configuration directory under the /Servers/ path in your workspace. This is a copy of the tc Server instance configuration, with a few notable alterations (like the removal of logging.properties). This is actually copied and rewritten for use each time you start your server – so it does serve some purpose. In fact, it’s what the server edit screen (below) is operating on.
- Right-clicking on the server and choosing “Properties” from the menu – this gets you the following relatively useless dialog:
What *does* help is clicking on the server to bring up its edit window:
You can see there are a few things that you can edit here, like ports. Those settings go into the config saved in the workspace under the “Configuration path”, which as mentioned above, is copied and rewritten when you start the server.
So where does the server actually run from? The definitive answer can be found in the launch configuration. To see this, click the “Open launch configuration” link under “General Information”.
Here I’ve clicked on the “Arguments” tab to see the JVM arguments. The catalina.base property there is where the actual running server instance goes (its confs, logs, apps, etc.). By default, it’s under the workspace in a generated directory below .metadata, which is what the server edit screen meant with the “Server Locations -> Use workspace metadata” setting. You can change that setting to “Use tc Server installation” and it will then actually use the original instance location as catalina.base, overwriting its config at each startup. But this would likely be more intuitive (and easier to find) for many users.
A few more notes:
- You won’t find a lot of logs in the logs/ directory of a running instance. You’ll pretty much only see the access log unless you add something else yourself (like a GC log). Eclipse/STS grabs the console output and doesn’t write it to a file.
- Although anything in webapps/ will be deployed (e.g. the manager app or insight dashboard app), when you add “modules” (apps) in STS, they will be placed in the wtpwebapps directory and deployed via context descriptor in conf/Catalina/localhost/.
Hope that helps a few of you out there to waste less time than I did figuring this out.
Filed under: eclipse, fedora, STS, tomcat | Tagged: catalina.base, configuration, console, launch configuration, logs, metadata, new server, runtime environment, tc server, vfabric, webapps, wtpwebapps |
Hi Luke,
Thanks for the article.
I have one quick question for you. I am trying to install tomcat in STS. I I can’t see any templates in the dialog that ask us to select the templates,
Go to Window/Preferences/Server/Runtime Environments and reconfigure path to Pivotal tc Server