simtabi/teamcity-installer

A containerized control console that installs, runs, backs up and upgrades a local JetBrains TeamCity stack without installing anything on your machine.

Requires Docker (OrbStack or Docker Desktop) with the Compose v2 plugin.

Tested on macOS/arm64 and Linux/x86-64. CI stands the stack up from nothing on Linux and runs the live checks against it, up to TeamCity's licence gate, which cannot be accepted unattended. WSL 2 is expected to work but has not been run on a real host. See platforms; reports welcome.

Install

git clone https://github.com/simtabi/teamcity-installer.git
cd teamcity-installer
make            # list what is available
make install    # guided setup

make lists everything it can do. Each target maps to a ./tc command of the same name, so use whichever you prefer — make is a convenience, not a dependency:

make            # list the targets
make up         # start the stack
make verify     # live end-to-end checks
make check      # lint, tests and verify — what CI runs

./tc            # or the interactive menu

That is the whole installation. ./tc is a POSIX shell script whose only dependency is the docker binary you already have; it builds a console image on first run and drops you into a guided setup. No JRE, no Tomcat, no system services, and nothing written outside this directory — TeamCity's data lives in named Docker volumes.

The first run asks a handful of questions, then brings up a TeamCity server, a PostgreSQL database and three build agents, with the database already configured so TeamCity's own setup wizard skips straight to the licence agreement — and it hands you the super user token that page asks for, which otherwise lives in a log file inside a Docker volume. It then creates the first administrator account for you, since a started server with no accounts is one nobody can sign in to.

Documentation

Guides

• Installation — requirements, what the first run does, how to remove it
• Getting started — from ./tc to a green build agent
• Users — the super user token, the first administrator, and adding more
• Data safety — what destroys data (only one command) and what does not
• Configuration — every setting in stack/.env and what changes it
• Architecture — how the pieces fit, and why the console is containerized
• Changelog — what changed, and when
• Roadmap — what v2 would be, and the triggers that would justify it
• Platforms — macOS, Linux and WSL, and exactly what has and has not been run
• Publishing — the open-source position, and what is left before a first push
• Release — the pinned TeamCity version and how to move it

Reference

• Console — the launcher, the menu, and non-interactive commands
• Wizard — guided setup and what each answer controls
• Stack — the generated compose file, services and volumes
• Agents — scaling, authorizing and pruning build agents
• Users — listing accounts and setting a password when nobody knows one
• Smoke build — proving the stack can build, not just that it looks healthy
• Backup — the three backup tiers and restore compatibility rules
• Upgrade — version changes, guards and the maintenance token
• Doctor — diagnostics and the exported bundle
• Verify — live end-to-end checks, and how they pair with the bats suite
• Logging — one log per tool, redaction, rotation and ./tc journal

Recipes

• Change the port
• Add an agent
• Switch to PostgreSQL
• Restore from a backup
• Enable Docker builds on agents
• Fix an agent that will not connect
• Fix a rejected super user token

Contributing & security

make check — lint, 89 unit tests and the live checks — must pass. Everything runs inside the console image, so none of it needs anything installed. Report security issues privately to the maintainers rather than opening a public issue.

License

MIT © 2026 Simtabi. Author: Imani Manyara.

TeamCity is a trademark of JetBrains s.r.o. This project is not affiliated with or endorsed by JetBrains and redistributes no JetBrains software — see NOTICE.