Promgen: a Django front end that writes your Prometheus configuration

The configuration moves from YAML into a database

Promgen is a configuration file generator for Prometheus, written as a Django web application. The jobs it lists are creating and managing Prometheus configuration files, and configuring alert rules and notification options.

That is the whole idea, and it is a trade rather than a free win. A Prometheus configuration is normally a YAML file in a Git repository, reviewed by a pull request. Moving it into a database behind a web form means anyone on the operations team can add a target without learning the file format, and that a change to an alert rule is a form submission rather than a pull request.

The cost is that the audit trail is now the database's write log rather than a diff in a repository, and a reviewer can no longer see a textual change. For a team that has never hand-edited Prometheus YAML, that is a good trade. For a team that already has a well-reviewed config in Git, it is likely a downgrade.

The upstream is LINE Corporation, with the copyright in the MIT licence dated 2017, and the project ships a CHANGELOG.md, a SECURITY.md and a CONTRIBUTING.md. The documentation site is at line.github.io/promgen, and the README links a slides deck that covers the original history of the project.

Five Docker commands and a settings directory

The bootstrap sequence is a set of one-shot Docker commands, and each one has a stated purpose.

First you create the settings directory and make it writable.

mkdir -p ~/.config/promgen
chmod 777 ~/.config/promgen

Then the bootstrap container prompts for connection settings for the database and the Redis broker, using the standard DSN syntax. The README gives the shape of both: a database example of mysql://username:password@hostname/databasename and a broker example of redis://localhost:6379/0.

docker run --rm -it -v ~/.config/promgen:/etc/promgen/ line/promgen docker-compose-bootstrap

After that, migrations are applied, the configuration is checked, and the first admin user is created.

docker run --rm -v ~/.config/promgen:/etc/promgen/ line/promgen migrate
docker run --rm -v ~/.config/promgen:/etc/promgen/ line/promgen check
docker run --rm -it -v ~/.config/promgen:/etc/promgen/ line/promgen createsuperuser

The check command is the one worth noting. It exists because the generated configuration is only useful if it is valid, and a validator that runs before the config is pushed is what stops a bad edit from taking Prometheus down.

The README says you can then use your favorite configuration management system to deploy to each worker, and notes that Promgen aims to use the XDG specs and follows suggestions made by the 12-Factor App. The PROMGEN_CONFIG_DIR environment variable in the Dockerfile is set to /etc/promgen, which is what makes the volume mount in every one of these commands the same path.

The worker has to live next to Prometheus

The run section describes two processes, and the placement constraint in it is the part that catches people.

The web worker is run with a port mapping and is typically balanced behind an NGINX instance.

docker run --rm -p 8000:8000 -v ~/.config/promgen:/etc/promgen/ line/promgen

The Celery worker is run without a port mapping, and the README says to make sure to run it on the same machine as your Prometheus server to manage the config settings.

docker run --rm -v ~/.config/promgen:/etc/promgen/ -v /etc/prometheus:/etc/prometheus line/promgen worker

The second volume mount, /etc/prometheus, is the mechanism. The worker writes the generated configuration into the Prometheus server's own configuration directory, and Prometheus is then told to reload. The compose file makes this explicit by mounting./docker into /etc/prometheus in both the worker and the prometheus service, and by starting Prometheus with --web.enable-lifecycle, which is the flag that permits a reload over HTTP.

So the architecture is a database-backed generator, a web UI to edit it, a Celery worker that regenerates the YAML, and Prometheus reading the result from a shared directory. The shipped design uses the filesystem rather than fetching configuration remotely.

The consequence for infrastructure is that the worker is not horizontally scalable in the usual sense, since each one needs the same filesystem view, and that a Prometheus server whose config directory is not writable by the worker is a misconfiguration the tool cannot work around.

A compose file that brings up the whole monitoring stack

The docker-compose.yml is a complete demo environment, and reading it is the fastest way to understand the pieces.

The web service builds from the repository, runs the command web -b 0.0.0.0:8000, and publishes 8080 to 8000. The worker service uses the same image and runs worker -l debug --queues prometheus,celery, with a comment explaining the two queues: the default celery queue handles notification processing and the prometheus queue handles deploying targets and similar work.

The shared environment block sets CELERY_BROKER_URL to redis://redis:6379/0, DATABASE_URL to mysql://promgen:promgen@mysql:3306/promgen, SECRET_KEY to docker-compose-demo and DEBUG to 1. The SECRET_KEY value is a demo placeholder and the DEBUG flag is on, so this file is a local playground rather than a deployment template.

The prometheus service is the upstream prom/prometheus image with the config file mounted, the storage path set to /prometheus, and the lifecycle flag enabled. It links to alertmanager and to blackbox, the blackbox-exporter, which is the standard Prometheus component for probing external endpoints over protocols like HTTP and ICMP.

The alertmanager service links back to web, which is the return path for notification callbacks. A second top-level file, docker-compose.yml at the repository root, is what the README's quick path uses, with docker-compose up -d to bring it up, docker-compose run web docker-compose-bootstrap to populate initial data, and docker-compose run web createsuperuser for an admin account.

Extension points declared as entry points

The pyproject.toml shows how Promgen is designed to be extended, and the mechanism is Python packaging entry points rather than a plugin directory.

There is a console script, promgen mapped to promgen.manage:main, and then two entry point groups. The promgen.discovery group registers promgen = promgen.discovery.default:DiscoveryPromgen, and the promgen.notification group registers alertmanager, email and linenotify, mapping to their modules under promgen.notification.

So a discovery backend and a notification backend are both pluggable, selected by which package is installed. A company that wants notifications through its own chat system implements one notification class and registers it, rather than patching the core.

The runtime dependencies explain what is doing the work. Django is pinned exactly at 4.2.26. djangorestframework with drf-spectacular provides the REST API and its schema, and django-rest-knox provides token authentication for it. django-guardian adds object-level permissions, which is what you need when different teams own different targets. django-sri adds subresource integrity attributes to generated static files, django-environ handles configuration, django-filter and kombu and celery handle the async side, and social-auth-app-django provides the single sign-on.

The project also ships Prometheus's own promtool in the image, copied from the prom/prometheus:v2.26.0 image, which is how the generated configuration gets validated against the real Prometheus parser rather than a reimplementation of it.

Optional dependency groups exist for dev, docs, and mysql, and the project requires Python 3.9 or newer.

Version churn and an old base image

The release history shows a project with a fast release cadence and one point of friction.

The tags are v0.74.1 from 2026-10-01, v0.74.0 from 2026-09-29 and v0.73.0 from 2026-03-10. The last push was on 2026-10-19, a few days after the newest tag, so the tree is current.

The project has not yet reached 1.0, and the version in pyproject.toml is 0.75.0.dev, which tells you the main branch is ahead of the last release.

The friction is the Dockerfile. It starts FROM python:3.9-alpine, and the Makefile uses SYSTEM_PYTHON ?= python3.9 with a.venv built from it, and the setuptools classifier list includes Programming Language:: Python:: 3.6. Python 3.9 reached end of life in October 2025, so a new installation of this image will pull a runtime that is no longer receiving security fixes, and the base image tag is a moving one that will drift as the alpine line advances.

There is a licensing detail worth flagging too. The repository has a licenses/ directory, a NOTICE file, and the third-party component inventory is present. The pyproject.toml pins Django to an exact version rather than a range, which is the right instinct for a service that holds your monitoring configuration, but it also means you are on the hook for tracking when that pin goes stale.

The security reporting route is stated as well: issues that are security related should go by mail to [email protected] and not through the public issue tracker.

Editorial conclusion

Promgen suits an operations team whose monitoring configuration changes often and whose team members are not comfortable editing YAML by hand, because targets, alert rules and notification routing become records in a database with a web interface on top. It is the wrong tool if your configuration is stable and small, since a checked-in prometheus.yml with a code review is simpler and leaves a better audit trail, and it is the wrong choice if you need Prometheus to keep running when the generator is down. Before adopting it, read the example settings files at docker/prometheus.yml and docker/alertmanager.yml, and note that the worker must run on the same machine as your Prometheus server, which is a placement constraint that has to be designed around.

Frequently asked questions

Official sources

1. License: MIT
2. line/promgen on GitHub
3. Project website
4. README
5. Releases