Metadata-Version: 2.4
Name: exordos_notification
Version: 1.2.8
Summary: The Platform Notification summary
Author-email: Genesis Corporation <eugene@frolov.net.ru>
License: Apache-2.0
Project-URL: homepage, https://github.com/exordos/exordos_notification/
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: oslo.config<10.0.0,>=3.22.2
Requires-Dist: restalchemy<17.0.0,>=16.0.1
Requires-Dist: gcl_iam<2.0.0,>=1.4.0
Requires-Dist: gcl_looper<2.0.0,>=1.2.3
Requires-Dist: gcl_sdk<4.0.0,>=3.6.0
Requires-Dist: bjoern>=3.2.2
Requires-Dist: Jinja2<4.0.0,>=3.1.5
Requires-Dist: bazooka<2.0.0,>=1.3.0
Requires-Dist: zulip<1.0.0,>=0.9.0
Provides-Extra: dev
Requires-Dist: tox>=4.56.4; extra == "dev"
Requires-Dist: tox-uv; extra == "dev"
Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: coverage>=4.0; extra == "test"
Requires-Dist: mock<6.0.0,>=3.0.5; extra == "test"
Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "test"
Requires-Dist: pytest-timer<2.0.0,>=1.0.0; extra == "test"
Provides-Extra: mypy
Requires-Dist: mypy; extra == "mypy"
Provides-Extra: ruff
Requires-Dist: ruff; extra == "ruff"
Provides-Extra: shellcheck
Requires-Dist: shellcheck-py; extra == "shellcheck"
Dynamic: license-file

# exordos_notification

Platform notification service for Exordos. Sends email confirmations and other transactional emails via a dedicated mailaas relay.

## Requirements

- `core` ≥ 0.0.0
- `dbaas` ≥ 2.2.4
- `mailaas` ≥ 0.0.0

## Installation

### 1. Install the element

```bash
exordos em elements install exordos_notification
```

This installs the notification service, its database, mail relay instance, IAM users and permissions. Wait for the element to become `ACTIVE`.

### 2. Configure site-specific settings

`exordos_notification` creates a VS variable `notification_noreply_address` with no default value — it is installation-specific (depends on your mail domain). Until it is set, the SMTP provider resource stays `NEW` and no emails are sent.

Copy the example manifest and fill in your noreply address:

```bash
cp exordos/manifests/site_config.yaml.j2.example exordos/manifests/site_config.yaml.j2
# Edit site_config.yaml.j2 and set the noreply address:
#   value: "noreply@your-mail-domain.example.com"
exordos em elements install exordos/manifests/site_config.yaml.j2
```

The `notification_site_config` element must be installed **once per deployment** after `exordos_notification` is active. Reinstalling `exordos_notification` will not overwrite it.

## Architecture

```
IAM (core)  ──event──►  exordos_notification  ──SMTP──►  mailaas exim4 DP
                             │
                             └── PostgreSQL (dbaas)
```

- **notification-cp** — the notification control plane VM (runs the notification service)
- **mailaas relay** — a dedicated `mail.instances` provisioned by metapaas; the notification service authenticates as the `smtp` account
- **VS variables** — `notification_noreply_address` (set via `site_config`) and `notification_endpoint` (auto-set by the manifest)

## Optional PostgreSQL backups

After `exordos_notification` and `communal_s3` are active, install the separate
backup element (requires `dbaas` ≥ 2.6.2 and `s3aas`):

```bash
exordos em elements install notification_pg_backup
```

`exordos/manifests/notification_pg_backup.yaml.j2` imports the existing
`notification_cluster_pg` and creates its backup policy, a private
`notification-pg-backups` bucket on `communal_s3`, a scoped S3 user, and generated
access, secret and encryption keys. It enables WAL archiving, weekly full backups
and daily incremental backups, retaining two full backups with their incremental
backups and WAL. Preserve the encryption key for restores.

The notification element can be installed without the backup element or S3.

## Restore PostgreSQL backups

After a successful backup is available, install the separate restore element:

```bash
exordos em elements install notification_pg_restore
```

`exordos/manifests/notification_pg_restore.yaml.j2` creates a new PostgreSQL 18
instance, `notification-pg-restored`, with 1 CPU, 2048 MiB RAM and a 20 GiB disk,
matching the source cluster. It imports the source cluster UUID from
`exordos_notification` and the bucket and credentials from `notification_pg_backup`,
then restores through the latest archived WAL. Both elements and `communal_s3`
must remain installed; DBaaS ≥ 2.6.2 is required.

For a restore to a specific time, change `restore_from.target` before installing:

```yaml
target:
  kind: time
  time: "2026-10-06T08:00:00Z"
```

The notification service continues using its original database; switching it to
the restored instance is a separate step. The restored instance has no backup
policy of its own. `restore_from` is applied only when creating the instance;
to repeat the restore, delete the restore element and install it again.
