This is an official JetBrains TeamCity server image. The image is suitable for production use and evaluation purposes.
More details about tags and components are here.
First, pull the image from the Docker Hub Repository
docker pull jetbrains/teamcity-server
Use the following command to start a container with TeamCity server
docker run --name teamcity-server-instance \
-v <path-to-data-directory>:/data/teamcity_server/datadir \
-v <path-to-logs-directory>:/opt/teamcity/logs \
-p <port-on-host>:8111 \
jetbrains/teamcity-server
where
- <path-to-data-directory> is the host machine directory to serve as the TeamCity Data Directory where TeamCity stores project settings and build results. Pass an empty directory for the brand new start. If the mapping is not set, you will lose all the TeamCity settings on the container shutdown.
- <path-to-logs-directory> is the host machine directory to store the TeamCity server logs. The mapping can be omitted, but then the logs will be lost on container shutdown which will make issues investigation impossible.
Due to security reasons, by default, the container is launched under user 1000.
If you need root permissions (user 0), a corresponding configuration key could be passed to Docker - docker run ... --user 0 ... jetbrains/teamcity-server.
Please, note that the running of Docker Containers under root user impose potential security vulnerabilities, including privilege escalation, thus a strong security assessment of the environment
is recommended prior to the start-up.
If TeamCity acts as an endpoint for a reverse proxy server like Nginx or Apache, it should be configured to provide secure cookies to end users.
To achieve that, you can pass an additional
-e TEAMCITY_HTTPS_PROXY_ENABLED=true parameter to the docker run command. With this parameter, TeamCity will be
started with an alternative server-https-proxy.xml configuration file which enables HTTPS options.
Alternatively, you can use a custom Tomcat configuration (see below).
If a TeamCity Server uses the HTTPS connection, it transmits encrypted traffic through port 443 by default.
For security reasons, some operating systems impose restrictions
on using "privileged" ports (typically, ports below 1024) for non-root users, such as user 1000. As a result, port 443 can be unavailable for processes running inside TeamCity Containers that are launched under user 1000.
To avoid this issue, do one of the following:
- (recommended) Map a non-privileged
8443port inside the container to the default HTTPS port443on a host machine. This solution allows TeamCity to be accessible via HTTPS without running the server under the root user (which is otherwise required for accessing the privileged port443).
docker run --name teamcity-server-instance \
...
-p 443:8443
...
jetbrains/teamcity-server
- Launch TeamCity Container under a root user. This approach is less secure and is generally avoided. Before running the server under the root user, perform a thorough security risk assessment.
docker run --name teamcity-server-instance \
...
--user 0
...
jetbrains/teamcity-server
TeamCity has Tomcat J2EE server under the hood, and if you need to provide an alternative configuration for the TomCat, you can use extra parameter
-v /alternative/path/to/conf:/opt/teamcity/conf
To get a sample of the current contents of the Tomcat's conf directory, use the docker cp command.
docker run --name teamcity-server-instance
-v <path-to-data-directory>:C:/ProgramData/JetBrains/TeamCity
-v <path-to-logs-directory>:C:/TeamCity/logs
-v <path-to-temp-directory>:C:/TeamCity/temp
-p <port-on-host>:8111
jetbrains/teamcity-server
See the <path-to-data-directory> and <path-to-logs-directory> descriptions above; <path-to-temp-directory> is the directory for temporary files.
We also suggest allocating a sufficient amount of resources to the Docker process, like in this example:
docker run --memory="6g" --cpus=4 -e TEAMCITY_SERVER_MEM_OPTS="-Xmx3g -XX:MaxPermSize=270m -XX:ReservedCodeCacheSize=640m" --name teamcity-server-instance
-v <path-to-data-directory>:C:/ProgramData/JetBrains/TeamCity
-v <path-to-logs-directory>:C:/TeamCity/logs
-v <path-to-temp-directory>:C:/TeamCity/temp
-p <port-on-host>:8111
jetbrains/teamcity-server
The details on the known problems in Windows containers are available in the TeamCity documentation.
TeamCity stores set of users and build results in an SQL database in addition to the Data Directory. By default, the TeamCity server uses an internal database stored on the file system under the data directory. However, production use requires an external database.
To use the server for production, make sure to review and apply the recommendations.
You will need at least one TeamCity agent to run builds. Check the jetbrains/teamcity-agent and jetbrains/teamcity-minimal-agent images.
To learn how you can start the TeamCity server together with agents in one go, see these Docker Compose samples.
When you need to pass additional environment variables to the server process, use the regular -e option. For example, to pass TEAMCITY_SERVER_MEM_OPTS environment variable, use:
docker run --name teamcity-server-instance \
-e TEAMCITY_SERVER_MEM_OPTS="-Xmx2g -XX:MaxPermSize=270m -XX:ReservedCodeCacheSize=640m" \
-v <path-to-data-directory>:/data/teamcity_server/datadir \
-v <path-to-log-directory>:/opt/teamcity/logs \
-p <port-on-host>:8111 \
jetbrains/teamcity-server
To run the maintainDB script (e.g. for the server backup), stop your running container and execute the following command from your host:
docker run -it --name teamcity-server-instance \
-v <path-to-data-directory>:/data/teamcity_server/datadir \
-v <path-to-log-directory>:/opt/teamcity/logs \
-p <port-on-host>:8111 \
jetbrains/teamcity-server \
"/opt/teamcity/bin/maintainDB.sh" "backup"
Be sure to keep all the local system paths the same with the main server start command.
To change the context of the TeamCity app inside a Tomcat container, pass -e TEAMCITY_CONTEXT=/context to the docker run command. The default one is ROOT, meaning that the server would be available at http://host/.
Make sure to check the generic TeamCity upgrade instructions. If you made no changes to the container, you can just stop the running container, pull a newer version of the image and the server in it via the usual command. If you changed the image, you will need to replicate the changes to the new TeamCity server image. In general, use Docker common sense to perform the upgrade.
The image is available under the TeamCity license. TeamCity is free for perpetual use with the limitation of 100 build configurations (jobs) and 3 agents. Licensing details.
This issue may occur for Docker images released prior to August 14, 2023 (TW-83304).
The Perforce Package key expired and was updated on August 14, 2023. This results in the following error that occurs if you modify the apt packages in images based on containers released before this date:
$ apt-get update
...
Err:15 https://package.perforce.com/apt/ubuntu focal InRelease
The following signatures were invalid: EXPKEYSIG 7123CB760FF18869 Perforce Software (Package Signing) <[email protected]>
…
To avoid this issue, execute this command in a container or include it in a Docker image build step before altering packages:
sudo apt-key adv --fetch-keys https://package.perforce.com/perforce.pubkey
Report issues of suggestions to the official TeamCity issue tracker.