Setting Up Prometheus on CasaOS: A Practical Guide

Prometheus is one of the most popular open‑source monitoring tools, and CasaOS makes it easy to run containerized apps on your home server. Prometheus is not in the standard CasaOS or the Big Bear CasaOS store, so requires a custom setup. But as I found out, getting Prometheus running smoothly on CasaOS requires a little extra care with configuration and filesystem permissions. Here’s how I set it up.

CasaOS Export Config

CasaOS apps are defined in YAML. Below is the configuration I used to deploy Prometheus (I mounted to an external drive):

name: yourprojectname
services:
  prometheus:
    cpu_shares: 90
    command: []
    container_name: prometheus
    deploy:
      resources:
        limits:
          memory: 8052M
    hostname: prometheus
    image: prom/prometheus:latest
    labels:
      icon: https://icon.casaos.io/main/all/prometheus.png
    mem_limit: "8443133952"
    ports:
      - target: 9090
        published: "9090"
        protocol: tcp
    restart: unless-stopped
    volumes:
      - type: bind
        source: /mnt/md0/prometheus/prometheus.yml
        target: /etc/prometheus/prometheus.yml
      - type: bind
        source: /mnt/md0/prometheus/data
        target: /prometheus
    network_mode: bridge
    privileged: false
x-casaos:
  author: self
  category: self
  icon: https://icon.casaos.io/main/all/prometheus.png
  port_map: "9090"
  scheme: http
  store_app_id: yourprojectname
  title:
    en_us: prometheus

Key points:

• Image: prom/prometheus:latest (you may want to pin a version for stability).
• Config file: Mounted from /mnt/md0/prometheus/prometheus.yml.
• Data directory: Mounted from /mnt/md0/prometheus/data to /prometheus.
• Port: Exposes Prometheus on http://:9090.

The Blank Page Problem

After deploying, I hit a frustrating issue: visiting http://:9090 showed a blank page. Checking the logs revealed:

Error opening query log file … file=/prometheus/queries.active err=”permission denied”
panic: Unable to create mmap-ed active query log

Prometheus was crashing in a restart loop because it couldn’t write to its data directory. This appeared to be a problem with the way I originally created the folder to be used and its permissions

Fixing Permissions

On the host, the data directory looked like this:

ls -ld /mnt/md0/prometheus/data
drwxr-xr-x 2 mir mir 4096 Nov 21 08:52 /mnt/md0/prometheus/data

It was owned by my user (mir:mir), but inside the container Prometheus runs as a different UID/GID. From the container’s perspective, it only had read/execute permissions — no write access.

Quick fix:

sudo chmod -R 777 /mnt/md0/prometheus/data

This made the directory world‑writable, allowing Prometheus to start and serve its UI correctly.

With permissions fixed, Prometheus started cleanly:

• Web UI accessible at http://:9090
• Config loaded from /mnt/md0/prometheus/prometheus.yml
• Metrics stored persistently in /mnt/md0/prometheus/data

Final Thoughts

Always check container logs when you see a blank page — they’ll point you to the root cause.

• Bind mounts inherit host permissions. Make sure the container’s user can write to mounted directories.
• Use user: in CasaOS YAML to align container UID/GID with your host user for smoother permission handling.
• Pin Prometheus versions instead of latest to avoid surprises when upstream changes.