Deploy Prometheus with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it straightforward to run Prometheus for metrics collection and alerting.

This guide walks you through deploying Prometheus with persistent time-series data, a basic scrape configuration, and automatic HTTPS for the web UI.

Prerequisites

• A VPS with at least 1 vCPU, 2 GB RAM, and 20 GB storage (storage scales with retention period)
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., prometheus.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  prometheus:
    image: prom/prometheus:latest
    restart: unless-stopped
    ports:
      - "9090:9090"
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=${PROMETHEUS_RETENTION:-15d}"
      - "--web.enable-lifecycle"
    volumes:
      - ../files/prometheus-data:/prometheus
      - ../files/prometheus-config/prometheus.yml:/etc/prometheus/prometheus.yml:ro
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:9090/-/healthy"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: You must create the Prometheus configuration file before deploying. See the configuration section below. Prometheus uses command-line flags rather than environment variables for most settings.

Prometheus Configuration File

Create a basic prometheus.yml configuration file at ../files/prometheus-config/prometheus.yml on your server:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

Add additional scrape targets for your monitored services as needed.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
PROMETHEUS_RETENTION	Data retention period (default: 15d)	30d

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Prometheus is primarily configured via its YAML config file and command-line flags rather than environment variables.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/prometheus-data — Time-series database (TSDB) files and WAL segments
• ../files/prometheus-config — Prometheus configuration file (prometheus.yml)

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/prometheus) because Dokploy may clean them during redeployment.

Important: The Prometheus container runs as user nobody (UID 65534). If you encounter permission errors, run chown -R 65534:65534 on the data directory from your server's shell.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., prometheus.yourdomain.com)
3. Set the container port to 9090
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Prometheus container.

Verifying the Deployment

1. Create the prometheus.yml config file in ../files/prometheus-config/ before deploying
2. In Dokploy, go to your project's Deployments tab and click Deploy
3. Watch the build logs — you should see the prometheus container pull and start
4. Check the Logs tab for the prometheus service. Look for: Server is ready to receive web requests
5. Open https://prometheus.yourdomain.com in your browser — you should see the Prometheus web UI
6. Navigate to Status > Targets to verify the self-scrape target is UP

Troubleshooting

Prometheus fails to start with "permission denied" The Prometheus container runs as UID 65534 (nobody). Ensure the data directory ../files/prometheus-data is writable by this user. Run chown -R 65534:65534 on both the data and config directories from your server's shell.

Configuration file not found Ensure ../files/prometheus-config/prometheus.yml exists and is a valid YAML file. Prometheus will refuse to start if the config file is missing or contains syntax errors. Validate your config by running promtool check config prometheus.yml locally.

Targets showing as DOWN Verify that Prometheus can reach the target endpoints from within its Docker network. For services running in the same Dokploy compose project, use the service name as the hostname. For external targets, ensure network connectivity and firewall rules allow access.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Prometheus in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Prometheus.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.