Prometheus

Collect and query time-series metrics from configured scrape targets.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Prometheus

Create portable native configuration files with managed settings.

Choose Editable configuration, or run selfhost app init prometheus --method configured.
Edit scrape jobs in native settings or files/prometheus.yml, then run Check configuration.

Customize deployment inputs (1)

Local HTTP port port: portDefault: 9090

Save this as inputs.json and adjust the values before initialization.

{
  "port": 9090
}

selfhost app --directory ./prometheus init prometheus --method configured --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./prometheus start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd prometheus
docker compose -f compose.yaml up -d

Edit native scrape configuration through App settings or files/prometheus.yml.
Run Check configuration before restarting to apply a file change.
Add remote scrape targets only across a trusted network and configure TLS/authentication for each target. Prometheus has no application OIDC login; protect its HTTP interface at the proxy.

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Prometheus, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "prometheus",
  "name": "Prometheus",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Actions for a linked container

Validate configuration

Validate the active configuration and referenced rules without changing them.

selfhost existing action EXISTING_ID check-config

Check readiness

Check whether Prometheus is ready to serve queries.

selfhost existing action EXISTING_ID check-ready

Before configuring integrations

The configuration remains ordinary Prometheus YAML. Recreate after saving a reviewed edit.
Add rule files through the portable project files and list them in rule_files.
No unauthenticated remote reload endpoint is enabled.
Protect the HTTP interface with a proxy or private network. Prometheus does not provide application OIDC login.

Prometheus integrations

Compose service: prometheus. These operations use the profile saved when this deployment is created.

Use the Editable configuration deployment method. The basic Docker image keeps its image-provided configuration. Validate with promtool before restarting.

Native settings

Changes use the app’s native YAML file. Unrelated settings are preserved.

Supported fields (5)

Default scrape interval scrape-interval: stringLength: 2 to unbounded characters
Rule evaluation interval evaluation-interval: stringLength: 2 to unbounded characters
External labels external-labels: json
Scrape jobs scrape-jobs: json
Rule files rule-files: string_list

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./prometheus config prometheus
selfhost app --directory ./prometheus plan prometheus changes.json
selfhost app --directory ./prometheus apply prometheus changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Validate configuration · schedulable

Validate the active configuration and referenced rules without changing them.

selfhost app --directory ./prometheus action prometheus check-config

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

Check readiness · schedulable

Check whether Prometheus is ready to serve queries.

selfhost app --directory ./prometheus action prometheus check-ready

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

prometheus: prom/prometheus:v3.15.0

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Prometheus documentation