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.

Quick start guide and usage

Getting started

1. Check the host first: ./tc preflight checks memory, disk, port availability and image architecture.
2. Run the guided setup: ./tc install (or Install from the ./tc menu), and say yes to starting the stack.
3. Open http://localhost:8111 and paste the super user token from ./tc token, leaving the username blank. The token is reissued on every server start, so take it fresh.
4. Accept TeamCity's licence agreement. The database step is skipped, because the console has already configured it.
5. Create the first administrator, either in TeamCity's setup screen or with ./tc admin (TC_ADMIN_USER and TC_ADMIN_PASSWORD set the account; a password is generated if unset).
6. Authorize the agents so they take builds: ./tc authorize.

Usage

./tc up         # start
./tc status     # health and ports; non-zero exit when not fully up
./tc logs server
./tc backup     # cold backup into backups/
./tc down       # stop, keeping data

The full walkthrough is in Getting started; everything else is in the documentation index.

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.