.vmoptions file for your installation, such as teamcity-server.vmoptions, and ensure it points to a supported JDK path. This approach guarantees that the TeamCity service uses the correct runtime without affecting other applications on the host machine.
Why Update TeamCity Java?
TeamCity relies heavily on Java for its core functionality, including build agents, the server interface, and database interactions. Over time, older Java versions reach end-of-life status, leading to security vulnerabilities and performance degradation. More commonly, recent updates to TeamCity introduce new features or dependencies that require a minimum Java version, typically Java 11 or higher depending on the specific release.
When running an outdated Java version, administrators often encounter deprecation warnings in the logs. These warnings indicate that certain APIs used by TeamCity are no longer recommended and may be removed in future releases. Ignoring these warnings can lead to unexpected failures during builds or even prevent the TeamCity server from starting after a major upgrade. Updating the JVM ensures compatibility with the latest patches and maintains system stability.
Locating the Configuration Files
The most critical step is identifying the correct configuration files for your operating system. Unlike some services that use generic system-wide configurations, TeamCity isolates its JVM settings within its own installation directory. You should never edit global system environment variables like JAVA_HOME if you want TeamCity to behave independently of other software.
For Linux distributions, including Ubuntu, the relevant files are typically located in the conf directory of the TeamCity installation path. Common paths include /opt/teamcity/conf/ or /usr/local/teamcity/conf/. Inside this folder, look for files ending in .vmoptions, specifically teamcity-server.vmoptions for the main server process and teamcity-agent.vmoptions for build agents. Windows installations follow a similar structure, usually found under C:\Program Files\JetBrains\TeamCity\conf\.
If you cannot find these files, check the bin directory where the start scripts reside. The scripts often reference the conf directory explicitly. Ensure you have administrative privileges before attempting to modify these files, as they are protected by standard user permissions.
Distinguishing Between Server and Agent Configs
It is vital to distinguish between the server and agent configurations. The teamcity-server.vmoptions file controls the memory and Java version for the web interface and database connections. The teamcity-agent.vmoptions file controls the resources available to individual build runners. If you are experiencing issues only on specific build machines, you may need to update the agent configuration separately. However, for general deprecation warnings related to the platform itself, the server configuration is the primary target.
Modifying the VM Options
Once you have located the correct .vmoptions file, open it with a text editor. You will see a list of flags that control the JVM behavior. To change the Java version, you generally do not need to add a new flag unless you are switching between different major versions installed on the same machine. Instead, verify that the -java-home parameter is correctly set.
# Example teamcity-server.vmoptions content
-Xms256m
-Xmx1024m
-java-home /usr/lib/jvm/java-11-openjdk-amd64
-Djava.util.logging.config.file=logging.properties
-Dfile.encoding=UTF-8If the -java-home line is missing, TeamCity defaults to the first Java installation found in your system PATH. Adding this line explicitly forces TeamCity to use the specified JDK. Replace the path with the actual location of your desired Java installation. For example, on Ubuntu, this might be /usr/lib/jvm/java-17-openjdk-amd64. On Windows, it would look like C:\Program Files\Java\jdk-17.
If you are upgrading from Java 8 to Java 11 or 17, ensure that any legacy parameters are still valid. Some older GC (Garbage Collector) flags may have changed syntax. Review the official Oracle or OpenJDK documentation for the target version to confirm parameter compatibility. After making changes, save the file and close the editor.
Restarting the Service
Changes to .vmoptions files do not take effect until the TeamCity service is restarted. On Ubuntu, you can restart the service using systemd commands. Run sudo systemctl restart teamcity to apply the new configuration. On Windows, open the Services management console, locate the TeamCity service, and select Restart.
After restarting, monitor the logs closely. Navigate to the Administration section of the TeamCity web interface and check the System Report. It should now display the updated Java version. If the service fails to start, review the log files located in the logs directory of the TeamCity installation. Look for errors related to invalid arguments or missing libraries, which often indicate a typo in the -java-home path.
Maintaining Compatibility Across Agents
Updating the server Java version is only part of the equation. Your build agents must also run compatible Java versions to execute builds successfully. If your agents are running on different operating systems, you must update each agent's teamcity-agent.vmoptions file individually. Alternatively, you can configure the agents to download their own JRE automatically by enabling the "Use embedded JRE" option in the agent configuration settings. This reduces manual maintenance overhead but requires sufficient disk space on each agent machine.
Regularly checking for Java updates is essential for security. Consider setting up a cron job or scheduled task to notify you when new LTS (Long Term Support) versions are released. This proactive approach prevents the accumulation of technical debt and ensures that your CI/CD pipeline remains robust and secure.
Frequently Asked Questions
Can I change the Java version globally for all applications?
No, it is strongly advised against changing the global JAVA_HOME environment variable just for TeamCity. Doing so may break other applications that rely on a different Java version. TeamCity’s isolated .vmoptions files allow you to manage its runtime independently.
What happens if I point to a non-existent Java path?
If the -java-home parameter points to a directory that does not contain a valid JDK, the TeamCity service will fail to start. The error logs will typically show a message indicating that the Java executable could not be found or that the version is unsupported.
Do I need to update Java on every build agent manually?
Not necessarily. You can configure build agents to use an embedded JRE provided by TeamCity. Enable this option in the agent configuration to automate updates and reduce manual intervention on each build machine.
Is Java 8 still supported in recent TeamCity versions?
Most recent major releases of TeamCity have dropped support for Java 8. While older versions may still run on Java 8, upgrading to Java 11 or 17 is required for new features and security patches. Check the release notes for your specific TeamCity version to confirm minimum requirements.
How do I verify the current Java version used by TeamCity?
You can verify the active Java version by visiting the System Report page in the TeamCity administration panel. Look for the "Java Version" field, which displays the exact runtime being used by the server process.