Notifications

Composia sends notifications for task results, backup events, image updates, and node status changes. Three notification channels are supported: Alertmanager, SMTP, and Telegram.

Configuration

All channels are configured in the controller config under notifications:

controller:
  notifications:
    alertmanager:
      enabled: true
      listen_path: "/api/v1/alerts"
    smtp:
      enabled: true
      host: "smtp.example.com"
      port: 587
      encryption: starttls
      username: "alerts@example.com"
      password: "REPLACE"
      from: "alerts@example.com"
      to:
        - "admin@example.com"
      on:
        - task_failed
        - backup_failed
      task_sources:
        - web
        - cli
    telegram:
      enabled: true
      bot_token: "REPLACE"
      chat_id: "REPLACE"
      on:
        - task_completed

Event types

The following notification event types are available:

Event	Trigger
`task_failed`	Any task ends with status `failed`.
`task_cancelled`	A task is cancelled before completion.
`task_completed`	A task finishes successfully.
`task_awaiting_confirmation`	A migration task reaches the confirmation step.
`backup_completed`	A backup task or scheduled backup finishes successfully.
`backup_failed`	A backup task or step fails.
`image_update_available`	An image check discovers a new version.
`image_update_applied`	An image update is applied.
`node_offline`	A node stops sending heartbeats.
`node_online`	A previously offline node resumes heartbeats.
`alertmanager_alert`	An Alertmanager alert is received when the controller is configured as an Alertmanager webhook receiver.

Each channel can filter which event types it should handle using the on list. An empty on list delivers all event types.

Task source filters

SMTP and Telegram channels support filtering by the source that triggered a task:

Source	Description
`web`	Actions triggered through the web UI.
`cli`	Actions triggered through the CLI.
`others`	Other sources.
`schedule`	Scheduled tasks (backups, maintenance).
`system`	System-generated tasks.
`auto_deploy`	Tasks generated by auto-deploy triggers.

When task_sources is empty, notifications are sent for all source types.

Alertmanager

The controller runs an embedded Alertmanager webhook receiver. When enabled, the receiver listens on the configured path:

alertmanager:
  enabled: true
  listen_path: "/api/v1/alerts"

Key	Type	Description
`enabled`	`bool`	Enabled by default when the section exists.
`listen_path`	`string`	HTTP path to receive Alertmanager webhooks. Defaults to `/api/v1/alerts`. Must start with `/` and contain no whitespace.

Point your Alertmanager instance at the controller’s address with this webhook URL. Alerts are forwarded to configured notification channels according to their event filters.

SMTP

SMTP delivers notifications by email:

Key	Type	Required when enabled	Description
`enabled`	`bool`	No	Enabled by default when the section exists.
`host`	`string`	Yes	SMTP server hostname.
`port`	`int`	Yes	SMTP port. Must be between 1 and 65535.
`encryption`	`string`	No	`none`, `starttls`, or `ssl_tls`. Defaults to `starttls`.
`username`	`string`	No	SMTP authentication username.
`password`	`string`	No	SMTP password.
`password_file`	`string`	No	Read password from a file.
`from`	`string`	Yes	Sender address.
`to`	`[]string`	Yes	Recipient addresses.
`on`	`[]string`	No	Event types to notify on.
`task_sources`	`[]string`	No	Task source filters.

Telegram sends notifications to a chat through a bot:

Key	Type	Required when enabled	Description
`enabled`	`bool`	No	Enabled by default when the section exists.
`bot_token`	`string`	Yes	Telegram bot token from BotFather.
`bot_token_file`	`string`	No	Read bot token from a file.
`chat_id`	`string`	Yes	Target chat ID.
`on`	`[]string`	No	Event types to notify on.
`task_sources`	`[]string`	No	Task source filters.

Last updated on Jul 16, 2026 • Renovate Bot

Image Updates