---
title: "Deploy Prometheus | (Just Updated) Metrics Behind A Login, Retention Capped To The Volume"
description: "Prometheus behind a login. Retention capped to your volume, targets via env"
category: "Observability"
url: https://railway.com/deploy/prometheus-or-just-updated-metrics-behin
---

# Deploy Prometheus | (Just Updated) Metrics Behind A Login, Retention Capped To The Volume

Prometheus behind a login. Retention capped to your volume, targets via env

**[Deploy Prometheus | (Just Updated) Metrics Behind A Login, Retention Capped To The Volume on Railway](https://railway.com/template/prometheus-or-just-updated-metrics-behin)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/prometheus-or-just-updated-metrics-behin/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** Observability

## Template content

### prometheus

- **Image:** ghcr.io/bon5co/prometheus-railway:3.15.0
- **Public domain:** Yes

## Documentation

# Deploy and Host Prometheus on Railway

Prometheus is the standard open-source monitoring system and time-series database: it scrapes
metrics from your services over HTTP, stores them, and answers PromQL queries for dashboards and
alerts. Grafana, Alertmanager and most of the cloud-native ecosystem speak to it.

This template runs Prometheus 3.15 from a thin wrapper around the official image: the Prometheus
web UI and API on a Railway public domain, a Railway volume holding the time-series database, and a
generated password in front of all of it.

## About Hosting Prometheus

- **It is behind a login from the first request.** Prometheus has no authentication of its own, so
  the stock image on a public Railway domain hands the query API, the loaded config and every
  scrape target to anyone with the URL. Here a password is generated per deploy
  (`PROMETHEUS_PASSWORD`), turned into a bcrypt web config at boot, and every route, including the
  API, answers `401` without it. The container refuses to start if the password is missing.
- **Retention cannot fill your volume.** The stock image keeps 15 days with no size limit, and a
  busy target can fill the disk before the time limit arrives. The entrypoint reads the volume's
  real size at boot and sets `--storage.tsdb.retention.size` to 80% of it.
- **Scrape targets come from variables.** Set `SCRAPE_TARGETS` to a comma-separated list such as
  `api.railway.internal:3000,worker.railway.internal:9100` and redeploy; no config file to edit.
  For anything more elaborate, put a full `prometheus.yml` in `PROMETHEUS_CONFIG`.
- **Data survives redeploys.** The volume at `/prometheus` is chowned at boot and the database runs
  as the unprivileged `nobody` user; samples written before a redeploy were read back after it.
- **Remote write is on.** `/api/v1/write` accepts pushes from Grafana Alloy, Agent or another
  Prometheus, behind the same password.

## Common Use Cases

- Metrics for the other services in your Railway project, scraped over the private network
- A data source for Grafana dashboards (use `PROMETHEUS_PRIVATE_URL` with basic auth)
- Alerting rules and long-lived service-level numbers for an app or a fleet of apps
- A remote-write target for agents that push metrics from outside Railway

## Dependencies for Prometheus Hosting

- One Railway volume for the time-series database (created by the template)

### Deployment Dependencies

- Prometheus documentation: https://prometheus.io/docs
- Basic auth in Prometheus: https://prometheus.io/docs/guides/basic-auth/
- Official image: https://hub.docker.com/r/prom/prometheus
- Wrapper source: https://github.com/bon5co/prometheus-railway

### Implementation Details

| Variable | Purpose |
| --- | --- |
| `PROMETHEUS_PASSWORD` | Password for the web UI, API and remote write, generated per deploy. The user name is `admin` (override with `PROMETHEUS_USER`). |
| `PROMETHEUS_PRIVATE_URL` | URL on the private network, for Grafana or other services in the project. |
| `SCRAPE_TARGETS` | Optional. Comma-separated `host:port` list to scrape. |
| `METRICS_PATH` | Optional. Path on those targets, default `/metrics`. |
| `RETENTION_TIME` | Optional. Default `15d`. |
| `RETENTION_SIZE` | Optional. Default 80% of the volume, for example `3GB`. |
| `PROMETHEUS_CONFIG` | Optional. A complete `prometheus.yml`, replaces the generated one. |

The healthcheck is off because every route needs the password; the service restarts on failure.

## Why Deploy Prometheus on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your
infrastructure so you don't have to deal with configuration, while allowing you to vertically and
horizontally scale it.

By deploying Prometheus on Railway, you are one step closer to supporting a complete full-stack
application with minimal burden. Host your servers, databases, AI agents, and more on Railway.


## Similar templates

- [Rootprint](https://railway.com/deploy/rootprint-1) — Open-source logs and traces with full-text search on object-storage.
- [Pyroscope profiling](https://railway.com/deploy/pyroscope-profiling) — Protected continuous profiling with durable Pyroscope storage.
- [SigOnly](https://railway.com/deploy/sigonly) — Deploy SigNoz with a working demo app & config in one click

Open this page in a browser: https://railway.com/deploy/prometheus-or-just-updated-metrics-behin