Metadata-Version: 2.5
Name: tutor-contrib-status
Version: 0.1.0
Summary: Standalone Open edX status page plugin for Tutor
Project-URL: Homepage, https://github.com/Abstract-Tech/tutor-contrib-status
Project-URL: Source, https://github.com/Abstract-Tech/tutor-contrib-status
Project-URL: Issues, https://github.com/Abstract-Tech/tutor-contrib-status/issues
Author: Abstract-Tech
License: AGPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.10
Requires-Dist: tutor<23.0.0,>=22.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pyyaml; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: tutor<23.0.0,>=22.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# tutor-contrib-status

A [Tutor](https://docs.tutor.edly.io) plugin that adds a public status page to your Open edX site.
It shows whether the LMS, Studio, the micro-frontends and the databases are up, with 90 days of history and past incidents.

It runs two services inside Tutor, pulled as ready-made images (nothing is built locally):
[`openedx-status-api`](https://github.com/Abstract-Tech/openedx-status-api) runs the checks and keeps the history,
[`openedx-status-web`](https://github.com/Abstract-Tech/openedx-status-web) is the page. Caddy serves it at `STATUS_HOST`.

## Install

```bash
pip install tutor-contrib-status
tutor plugins enable status
tutor config save
tutor images pull status-api status-web
tutor local start -d
```

Then create a DNS `A` record for `STATUS_HOST` (default `status.<LMS_HOST>`).

Notes:

- `tutor local start -d` starts all services. This matters: Tutor's `permissions` service gives the API
  (user 10001) ownership of `data/status` on every start. If you start only `status-api`, create that folder
  and `chown 10001` it yourself.
- The check list is written to `$(tutor config printroot)/env/plugins/status/config/checks.yml` and mounted
  read-only. Tutor does not change file permissions, so the file gets the default ones of your `umask`. If you
  use a very strict `umask` (for example `077`) the API cannot read it: run `chmod -R a+rX` on that `config` folder.
- With `tutor dev` there is no Caddy route. The page is on `http://localhost:8085` (`STATUS_DEV_WEB_PORT`), the API on `http://localhost:8086`.

## Settings

Change a setting with `tutor config save --set KEY=value`.

| Key | Default | What it does |
| --- | --- | --- |
| `STATUS_HOST` | `status.<LMS_HOST>` | Address of the status page |
| `STATUS_TITLE` | `<PLATFORM_NAME> status` | Title of the page |
| `STATUS_IMAGE_TAG` | `latest` | Image tag |
| `STATUS_API_DOCKER_IMAGE` | `ghcr.io/abstract-tech/openedx-status-api:<tag>` | API image |
| `STATUS_WEB_DOCKER_IMAGE` | `ghcr.io/abstract-tech/openedx-status-web:<tag>` | Web image |
| `STATUS_DEV_WEB_PORT` | `8085` | Host port of the status page with `tutor dev` |
| `STATUS_FAIL_THRESHOLD` | `3` | Failed checks in a row before an incident opens |
| `STATUS_RETENTION_DAYS` | `90` | How long history is kept |
| `STATUS_INTERVAL` | `60` | Seconds between checks |
| `STATUS_PUBLIC_SCHEME` | `https` if `ENABLE_HTTPS`, else `http` | Scheme used for the public checks |
| `STATUS_CHECK_LMS_PUBLIC` | `true` | Check the LMS at its public address (`lms-public`). |
| `STATUS_CHECK_STUDIO_PUBLIC` | `true` | Check Studio at its public address. Set `false` to check `http://cms:8000` instead (for example when the Studio host name does not work inside Docker). |
| `STATUS_CHECK_MFE` | `true` | Check the micro-frontends (needs the `mfe` plugin) |
| `STATUS_CHECK_DATABASES` | `true` | Check MySQL, MongoDB and Redis |
| `STATUS_MYSQL_USER` | `<OPENEDX_MYSQL_USERNAME>` | User for the MySQL check. A read-only user is enough. |
| `STATUS_MYSQL_PASSWORD` | `<OPENEDX_MYSQL_PASSWORD>` | Its password |
| `STATUS_REDIS_PASSWORD` | `<REDIS_PASSWORD>` | Redis password. Empty means no password. |

On local installs where `LMS_HOST` resolves to 127.0.0.1 (for example `local.openedx.io`), the public checks fail
from inside the container. Set `STATUS_CHECK_LMS_PUBLIC=false` and `STATUS_CHECK_STUDIO_PUBLIC=false` there.

## Add your own checks

Use the `status-checks` patch from your own Tutor plugin:

```python
hooks.Filters.ENV_PATCHES.add_item(
    ("status-checks",
     "- id: forum\n  name: Forum\n  group: Services\n  kind: tcp\n  target: forum:4567\n")
)
```

The patch is added to the end of the `checks:` list, so each entry starts with `- `. The fields of a check
are described in the README of [`openedx-status-api`](https://github.com/Abstract-Tech/openedx-status-api).
Never put a password in a check. Use `password_env` with the name of an environment variable of the
`status-api` container instead. Run `tutor config save` and run `tutor local restart status-api` to apply changes.

## Always-on page

The page runs inside Tutor, so it stops when Tutor stops (`tutor local stop`).
For a page that stays up, run it outside Tutor: see the `deploy/` folder in
[`openedx-status-api`](https://github.com/Abstract-Tech/openedx-status-api).

## Related

- [openedx-status-api](https://github.com/Abstract-Tech/openedx-status-api): checks, history, API
- [openedx-status-web](https://github.com/Abstract-Tech/openedx-status-web): the page

## Development

```bash
pip install -e '.[dev]'
pytest
```

## License

AGPL-3.0-only. See [LICENSE](LICENSE).
