NOTE: PromDash is deprecated. We recommend Grafana for visualization of Prometheus metrics nowadays, as it has native Prometheus support and is widely adopted and powerful.
Dashboards for Prometheus.
$ bundle exec rake
$ RAILS_ENV=test bundle exec rake karma:run
JSHint is run against all pull requests. To shorten the feedback loop, it is recommended that you run JSHint locally. With NPM installed, install and run JSHint:
$ npm install jshint -g
$ jshint app/assets/javascripts
You need need to install multiple dependencies for the full development cycle.
Here is the rundown for Ubuntu 14.04 LTS as a reference. If you run into errors
with bundle
, the most likely reason is that the database servers are not
properly installed with dev headers/libs.
sudo apt-get install nodejs nodejs-legacy npm
sudo apt-get install ruby-full
(details)sudo apt-get install libmysqlclient-dev
(details)sudo apt-get install postgresql-9.{3|4} postgresql-server-dev-9.{3|4}
(details)sudo apt-get install sqlite3 libsqlite3-dev
(details)Install gems:
bundle
Set up your database:
cp config/database.yml.example config/database.yml
RAILS_ENV=development bundle exec rake db:setup
Start the Rails server:
bundle exec rails s
In production mode, you need to define a number of environment variables to configure the database parameters:
DATABASE_URL="mysql2://username:password@host/database"
RAILS_ENV="production"
Note: Besides MySQL, you may also use any other Rails-compatible relational database like PostgreSQL or SQLite3. See also http://edgeguides.rubyonrails.org/configuring.html.
Create a self-contained Ruby environment and precompile assets:
make build
Run the production server from the bundled environment:
bin/env bin/bundle exec bin/thin -p $PORT start
To deploy PromDash with Docker, use the prom/promdash Docker image. By default, the image will start the thin webserver webserver in production mode. To run rake tasks like migrations, you can specify any kind of command as parameter to the Docker image.
The following is a quick-start example for running PromDash with a file-based local database.
First, create the SQLite3 database in a shared local Docker volume on the host:
docker run --rm -v /tmp/prom:/tmp/prom \
-e DATABASE_URL=sqlite3:/tmp/prom/file.sqlite3 \
prom/promdash ./bin/rake db:migrate
Now, we launch PromDash with the database we've just created:
docker run -p 3000:3000 -v /tmp/prom:/tmp/prom \
-e DATABASE_URL=sqlite3:/tmp/prom/file.sqlite3 \
prom/promdash
You can pass parameters directly to the thin server with:
docker run -p 3000:4000 -v /tmp/prom:/tmp/prom \
-e DATABASE_URL=sqlite3:/tmp/prom/file.sqlite3 \
prom/promdash ./bin/thin -a localhost -p 4000 start
To deploy PromDash behind a reverse proxy you can set a global path prefix
using both environment variables PROMDASH_PATH_PREFIX
and RAILS_RELATIVE_URL_ROOT
.
Once set all URLs will start with the given prefix.
One simple way to secure your Prometheus deployment with authentication is
running a reverse proxy, Prometheus, and PromDash on the same machine. The goal
is to have a publicly available deployment for authenticated users via your
reverse proxy while restricting raw IP:PORT
access. We won't cover any
details on how to configure your reverse proxy, as it depends on what you are
using.
As PromDash executes Prometheus queries directly from the client it is simpler to use a single domain. This makes the server side ACL management simpler and the client requests already authenticated.
Reverse proxy (e.g. nginx, HAProxy)
http(s)://dash.example.com/dash
to backend localhost:3000
http(s)://dash.example.com/prom
to backend localhost:9090
Run Prometheus with binding only to localhost to restrict direct external
access over the network that would circumvent your authentication. Remember to
pass the path portion in -web.external-url
. Example for Docker:
(full reference)
docker run -p 127.0.0.1:9090:9090 -v /prometheus-data \
prom/prometheus -config.file=/prometheus-data/prometheus.yml \
-web.external-url "http://dash.example.com/prom"
Run PromDash in a similar fashion. Once PromDash is running add a
Prometheus server with http://dash.example.com/prom/
in the web UI at
http://dash.example.com/dash
.
docker run -p 127.0.0.1:3000:3000 -v /tmp/prom:/tmp/prom \
-e DATABASE_URL=sqlite3:/tmp/prom/file.sqlite3 \
-e PROMDASH_PATH_PREFIX=/dash \
-e RAILS_RELATIVE_URL_ROOT=/dash \
prom/promdash
Finally check that your reverse proxy is working as expected by visiting
dash.example.com/dash
and dash.example.com/prom
. Both should prompt you for
credentials, e.g. HTTP basic auth. You can use a Chrome incognito tab to force
authentication. Next visit the public facing IP address on the ports
<IP>:3000/dash
and <IP>:9090/prom
to verify they are in fact giving a page
load error.
Before deploying a new version of PromDash, follow this checklist:
bundle exec rake db:migrate
)?After deploying a new version:
Since we frequently need to display various PromDash views in inline frames, we
disabled Rails' default header X-Frame-Options: SAMEORIGIN
for all views:
https://github.com/prometheus/promdash/commit/5b1da215296b5316568ad7c8449652f0d7f74ebe
If you are worried about clickjacking attacks, it is safe to revert this commit as long as you don't need to display dashboards in iframes.