The Countly Docker Compose deployment ships with a Makefile that wraps docker compose and adds tier awareness. This guide explains what the wrapper does, lists every target, and shows the workflows it is designed to support. If you are comfortable with raw docker compose commands, every target has an equivalent you can reach for instead, but the Makefile is shorter and remembers your active tier for you.
Why the wrapper exists
Two things, mostly. First, every common operation becomes a single short command (make up, make logs, make ps) instead of a longer docker compose invocation. Second, when you apply a tier with make up TIER=…, the wrapper writes the tier name to .active-tier and inherits it on every subsequent command. That means you do not have to repeat the tier flag on every ps, logs, or restart.
Prerequisites
Before you begin, confirm that:
- You are working inside the
dockerized_deploy/directory of the Countly deployment. - Docker Engine and the Docker Compose plugin are installed.
GNU
makeis available on the host. TheMakefileuses GNU-specific directives (ifneq,?=) that BSD make does not parse. On Linux, the defaultmakeis GNU. On macOS, install GNU make withbrew install makeand invoke it asgmakeif your systemmakeis BSD.- You have edited
.envwith the required values (see the deployment guide for first-time setup).
Available Targets
The full set of Makefile targets, what each does, and the equivalent raw docker compose command if you prefer to skip the wrapper:
| Target | What It Does | Equivalent |
|---|---|---|
make up | Start the stack with single-instance defaults (no TIER). | docker compose up -d |
make up TIER=T32-128 | Start the stack at the named tier, persist the tier to .active-tier. | Multi-flag docker compose with -f tiers/T32-128.compose.yml and --env-file tiers/T32-128.env |
make down | Stop and remove the containers. Clears .active-tier. Disk data is preserved. | docker compose down |
make ps | List running services in the active tier. | docker compose ps |
make logs | Follow the last 200 lines from every service in the active tier. | docker compose logs -f --tail=200 |
make restart | Restart every running service in place (no config re-evaluation). | docker compose restart |
make pull | Pull updated images for every service in the active tier. | docker compose pull |
make tier-list | List every available tier name. | (none — convenience target) |
Targeting a single service
The Makefile targets operate on the whole stack. To act on one specific service (for example, follow logs from countly-api only, or restart only countly-ingestor), drop down to raw docker compose. The active tier remains in effect because docker compose reads the same docker-compose.yml from the working directory.
docker compose logs -f countly-api docker compose restart countly-ingestor
How Tier Awareness Works
When you run make up TIER=<name>, the wrapper does three things:
- Validates that
tiers/<name>.envexists. If it does not, the command fails and prints the list of available tiers. - Writes the tier name to
.active-tierin the current directory. - Calls
docker composewith the matching tier override files (-f tiers/<name>.compose.ymlwhen present, plus--env-file tiers/<name>.env).
Subsequent commands like make ps, make logs, and make restart read .active-tier at the top of the Makefile and reuse the same tier overrides automatically. You only pass TIER= again when switching to a different tier.
When the active tier resets
make down removes .active-tier, so the next bare make up falls back to the single-instance defaults baked into docker-compose.yml. To preserve the tier across a stop-and-restart cycle, use make restart instead of make down && make up.
Common Workflows
Starting the Stack for the First Time
After populating .env, bring everything up with single-instance defaults and confirm services reach healthy status:
make up make ps
First boot takes about three to five minutes while MongoDB initializes its replica set, ClickHouse bootstraps the schema, and Kafka Connect registers the ClickHouse sink connector.
Applying a Tier
When the host is larger than the single-instance defaults assume, pick a tier that matches the host size:
make up TIER=T32-128 make ps
The chosen tier is written to .active-tier. Sibling commands (make ps, make logs, make restart, make pull) inherit it automatically until you switch tiers or run make down.
Following Logs and Checking Status
To watch what the stack is doing in real time:
make logs # follow last 200 lines from every service make ps # one-shot status snapshot
For logs from one specific service, drop down to docker compose:
docker compose logs -f countly-api
Pulling Updated Images
When a new Countly image is published, refresh the local cache and recreate any container whose image reference changed:
make pull make up
The make up step is what actually applies the new images. make pull on its own only updates the local cache; running containers continue with the image they started from.
Switching Tiers
To resize the running stack, re-run make up with the new tier name:
make up TIER=T64-256
Compose recreates only the containers whose effective configuration changed. Kafka rebalances aggregator partitions across the new replica count automatically.
Tearing the Stack Down
To stop the stack while keeping disk data intact:
make down
This removes the containers and clears .active-tier. The next bare make up starts at the single-instance defaults again. Persistent data under ./data/ is left untouched.
Common Issues and Gotchas
make tier-list to print every available tier name. Each line is a tier you can pass to make up TIER=. To inspect the resource caps and replica counts each tier applies, read tiers/<name>.env directly, or see tiers/README.md.make: command not foundMakefile requires GNU make. On Linux, install it with your package manager (apt install make, dnf install make, etc.). On macOS, install it with brew install make and either invoke it as gmake or place the Homebrew binary ahead of /usr/bin/make on your PATH.Unknown tier: T… error on make uptiers/*.env and did not find a match. Run make tier-list to see the available tier names. Tier names are case-sensitive and follow the pattern T<vCPU>-<RAM>.cat .active-tier to confirm which tier is currently applied. If it is empty or missing, the stack is on single-instance defaults. To switch, run make up TIER=<name> again. make restart does not change the active tier — it only restarts the existing containers in place..env are not taking effect.env, run make up again. Compose recreates any container whose effective environment changed and leaves the rest alone. make restart does not pick up .env changes.