Published

Prometheus

Open-source metrics server and time series database (Apache-2.0, CNCF): it scrapes metrics over HTTP, stores them locally and answers PromQL queries and alert rules. Fits a team that wants its server and app metrics, and Grafana dashboards on them, on its own server.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 10,000 active series scraped every 15 s (about 667 samples/s) with the default 15-day retention: Prometheus itself and a few exporters on a handful of servers.	0.25 vCPU · 0.5 GiB RAM · 2.5 GiB disk	0.42 vCPU · 2.1 GiB RAM · 12.19 GiB disk
MediumEstimate	Up to 100,000 active series every 15 s (about 6,667 samples/s), 15-day retention, with a few Grafana dashboards and alert rules querying it.	1 vCPU · 1.5 GiB RAM · 18.6 GiB disk	1.32 vCPU · 3.3 GiB RAM · 30.705 GiB disk
HeavyEstimate	Up to 1,000,000 active series every 15 s (about 66,667 samples/s), 15-day retention, many dashboards and recording rules: near the limit of one server.	2 vCPU · 8 GiB RAM · 183 GiB disk	2.52 vCPU · 11.1 GiB RAM · 219.765 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Prometheus (app)	0.25 / 0.5 / 2.5	1 / 1.5 / 18.6	2 / 8 / 183	[5][7][12][13][16][20][22]

How the estimates are worked out

Prometheus · Light: No upstream CPU or RAM figure. RAM: about 4.5 GiB per million series at 15 s (2 + 2.5 GiB, community figure) → 0.045 GiB, plus an assumed 0.25 GiB for the Go runtime, UI and rules and room for queries → 0.5. vCPU: 667 samples/s → a quarter core. Disk: 1,296,000 s × 667/s × 2 B = 1.609 GiB, +10% for compaction (0.161), WAL minimum 3 × 128 MB (0.375). Image 106,733,760 B compressed (0.099 GiB) + 254,005,248 B unpacked (0.237 GiB), both kept by the containerd store = 0.336 GiB. Sum 2.481 → 2.5.
Prometheus · Medium: RAM: 100,000 series × 4.5 GiB/million = 0.45, + 0.25 base, + 0.745 for one query at the --query.max-samples limit (50,000,000 × 16 B per sample) = 1.445 → 1.5. vCPU: one core for 6,667 samples/s, compactions and dashboard queries. Disk: 1,296,000 s × 6,667/s × 2 B = 16.093 GiB, +10% compaction (1.609), WAL for 3 h at 8 B/sample (0.536), image 0.336 = 18.574 → 18.6.
Prometheus · Heavy: RAM: 4.5 GiB for 1M series (community figure, GC doubling included) + 0.25 base + 2 × 0.745 for two queries at --query.max-samples = 6.24, rounded up to 8 for the page cache of m-mapped chunks and blocks that queries read. vCPU: 2 for 66,667 samples/s, compactions and rules. Disk: 1,296,000 s × 66,667/s × 2 B = 160.933 GiB, +10% compaction (16.093), WAL for 3 h at 8 B/sample (5.364), image 0.336 = 182.726 → 183.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Prometheus	9090/tcp	Internal only	Web UI, PromQL HTTP API and /metrics; no login, so keep it on the internal network	[1][2][6][7]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Prometheus	65534:65534	`nobody`	No	`/prometheus/etc/prometheus`	[1][2][8]

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
PrometheusDerived	0	0	0	[16][17]

What the growth figures rest on

Prometheus: Time-based retention (15d by default) deletes blocks older than the window, so the TSDB stops growing once it holds 15 days, which the preset disk already covers. Raising retention adds about 3.219 GiB per extra 30 days at this level (2,592,000 s × 667 samples/s × 2 B). Expired blocks can take up to 2 h to be removed.
Prometheus: Time-based retention (15d by default) deletes blocks older than the window, so the TSDB stops growing once it holds 15 days, which the preset disk already covers. Raising retention adds about 32.187 GiB per extra 30 days at this level (2,592,000 s × 6,667 samples/s × 2 B). Expired blocks can take up to 2 h to be removed.
Prometheus: Time-based retention (15d by default) deletes blocks older than the window, so the TSDB stops growing once it holds 15 days, which the preset disk already covers. Raising retention adds about 321.865 GiB per extra 30 days at this level (2,592,000 s × 66,667 samples/s × 2 B). Expired blocks can take up to 2 h to be removed.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Stop Prometheus (docker compose stop prometheus) and copy both volumes, /prometheus and /etc/prometheus. A TSDB snapshot through the admin API is the online alternative, if you enabled it. [16][19]

Upgrade steps

Inside the 3.13 LTS line (selected fixes, supported until 2027-07-31): back up first, set the new v3.13.x tag in the Compose file, then run docker compose pull and docker compose up -d. Both volumes are kept. [3][9]
Before moving to a newer minor or the next LTS, read the CHANGELOG entries in between, and check your edited config with docker compose exec prometheus promtool check config /etc/prometheus/prometheus.yml after the new image is up. [1][14]
On start Prometheus replays the WAL before it serves queries; wait for /-/ready and look at docker compose logs prometheus before you rely on the new version. [4][16]

Roll back

Stop the stack, restore both volumes from the copy taken before the upgrade, pin the previous tag and run docker compose up -d. [14][15]DerivedUpstream documents downgrade limits only from 3.x to 2.x (a 3.x TSDB is readable by 2.55 or newer). An older binary may not read WAL records written by a newer one (3.13.4 fixed that for agent mode only), so restoring the copy is the safe path.

Known breaking changes

In 3.13.0: Credentials (Authorization header, basic auth, bearer token, OAuth2, custom headers) are no longer sent after a redirect to another host, in scraping, remote read/write, alerting and service discovery. The experimental duration functions min() and max() became min_of() and max_of(). [14]
In 3.11.0: Hetzner service discovery: __meta_hetzner_datacenter is deprecated, and for the hcloud role it is set to stop working after 1 July 2026; relabel with __meta_hetzner_hcloud_location and __meta_hetzner_robot_datacenter instead. [14]
In 3.9.0: The native-histograms feature flag does nothing now: native histograms are stable, but they are scraped only when scrape_native_histograms is set in the config (added in 3.8). [14][15]
In 3.0.0: From 2.x: in PromQL . matches newlines and range selectors exclude the left boundary; le and quantile values are normalised (le="1" becomes "1.0"); scrapes without a valid Content-Type fail unless fallback_scrape_protocol is set; Alertmanager API v1 and holt_winters are gone. Go through 2.55 first: a 3.x TSDB can only be read back by 2.55 or newer. [14][15]

Limits

One server, no clustering or replication: the local TSDB is a single-node database. High availability or retention beyond one disk needs remote_write to another system. [16]
Retention is 15 days by default. Set it in prometheus.yml under storage.tsdb.retention (time, or size at most 80-85% of the disk); the retention command-line flags are deprecated. [7][16][17]
The template scrapes only Prometheus itself. Add targets in the /etc/prometheus volume: docker compose exec prometheus vi /etc/prometheus/prometheus.yml, check it with promtool check config, then reload with docker compose kill -s SIGHUP prometheus. [1][2][4][5]
In the generated file every app has its own network (<app>-internal), so Prometheus cannot scrape other apps' services by name, and Grafana cannot query it, until you add the other service's network to the service that connects (for example prometheus-internal to Grafana). [5][6]
Keep the data volume on a local filesystem: NFS (including AWS EFS) and other non-POSIX filesystems are not supported and can corrupt the TSDB beyond repair. [16]

Security

Prometheus has no login: anyone who reaches port 9090 reads every series and uses the whole query API. The template keeps it on its own Docker network (prometheus-internal); you reach it only through the loopback publish and an SSH tunnel. For Grafana in the same file, add its service to that network and use http://prometheus:9090. [3][6]
Basic auth and TLS are available only through a web config file (--web.config.file, bcrypt-hashed passwords), which upstream marks experimental and the template does not set. Do not expose port 9090 through a proxy without authentication in front of it. [6][18]
The admin API (deleting series, snapshots) and the lifecycle endpoints (/-/reload, /-/quit) stay off, as in the image defaults. Turn them on only while untrusted users cannot reach the port. [6][7]
The container runs as nobody (65534:65534), not root, and the image already owns /prometheus and /etc/prometheus by that user, so named volumes need no chown. [1][2]

Backup

Back up both volumes. A copy of /prometheus taken while it runs is coherent if it leaves out chunks_head/, wal/ and wbl/, at the cost of the last 2-3 hours; stopping Prometheus first keeps everything. Back up /etc/prometheus with every config change. [16]
For an online backup with recent data, enable --web.enable-admin-api and POST /api/v1/admin/tsdb/snapshot; the snapshot lands in /prometheus/snapshots. That flag needs a command that repeats the image's default CMD. [1][3][19]