https://github.com/uninett/argus
Argus is an alert aggregator for monitoring systems
https://github.com/uninett/argus
api api-rest-server dashboard kiss-principle monitoring notifications postgresql python unix-philosophy webapp
Last synced: 4 days ago
JSON representation
Argus is an alert aggregator for monitoring systems
- Host: GitHub
- URL: https://github.com/uninett/argus
- Owner: Uninett
- License: gpl-3.0
- Created: 2019-09-25T06:26:37.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-09T09:23:00.000Z (11 months ago)
- Last Synced: 2025-04-09T15:03:35.821Z (11 months ago)
- Topics: api, api-rest-server, dashboard, kiss-principle, monitoring, notifications, postgresql, python, unix-philosophy, webapp
- Language: Python
- Homepage:
- Size: 4.8 MB
- Stars: 19
- Watchers: 4
- Forks: 14
- Open Issues: 274
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Argus
[](https://github.com/Uninett/Argus/actions)
[](https://codecov.io/gh/Uninett/Argus)
[](https://github.com/astral-sh/ruff)
[](https://www.djlint.com)
[](http://argus-server.rtfd.io/en/latest/)
Argus is a platform for aggregating incidents across network management systems, and
sending notifications to users. Users create notification profiles that define which
incidents they subscribe to. See [Argus docs](http://argus-server.rtfd.io/en/latest/) for more details.
This repository hosts the backend built with Django. There is also a
[REACT SPA frontend](https://github.com/Uninett/Argus-frontend).
See also the the [Python client library](https://github.com/Uninett/pyargus).
> [!IMPORTANT]
> * API v1 has been deprecated. API v2 is the new stable. Support for API v1
> will be dropped in version 2.0 of argus-server. Please upgrade your glue
> services!
> * Support for the REACT frontend will be dropped in version 2.0 of
> argus-server. Please try out the new built-in one.
## Installation
There are several ways to install Argus.
### Prerequisites
#### Requirements
* Python 3.10+
* Django 4.2 or 5.1
* pip
* PostgreSQL 14+
> [!WARNING]
> The next [Django LTS](https://docs.djangoproject.com/en/5.2/releases/5.2/)
> will not support any PostgreSQL older than version 14!
> [PostgreSQL 17.4](https://www.postgresql.org/docs/17/release-17-4.html) is
> the newest version as of this writing.
#### Optional requirements
* Docker and Docker Compose to run Argus in Docker. This will also run
a PostgreSQL server for you.
#### Optional: New frontend
You need to have the new frontend dependencies installed.
```
pip install argus-server[htmx]
```
will do it.
#### Optional: Old frontend
> [!WARNING]
> Support for this backend will be dropped in version 2 of argus-server. Please
> try the new backend.
The old frontend needs:
* **Redis**. Redis backs the websockets, in order to push realtime updates to
the frontend. See the included `docker compose` file for the quickest way.
* [Argus-frontend](https://github.com/Uninett/Argus-frontend/), javascript that
uses the API.
Get the python dependencies via:
```
pip install argus-server[spa]
```
#### Optional: Dataporten registration
Dataporten authentication is supported by Argus and can be used to log into
Argus-frontend. Refer to the
[Dataporten](https://argus-server.rtfd.io/en/latest/authentication.html#dataporten)
section of the documentation to learn about Dataporten registration, and how to
set it up with Argus.
### Install Argus using pip
You can also install Argus with `pip` via PyPI. The package name is `argus-server`:
```console
$ pip install argus-server
```
If you are using the PyPI package in production, please note: The file
`requirements.txt` contains the pinned versions of dependencies that the
release was tested on. The file `constraints.txt` is for controlling versions
of sub-dependencies so as to not poison the pyproject.toml.
To update the dependency lock-files, use `tox`:
```console
$ pip install "tox>=4"
$ tox run -e upgrade-deps -- -U
```
To upgrade a single dependency, replace the `-U` flag with `-P PACKAGENAME`.
To install from the lock-file use pip:
```console
$ pip install -c constraints.txt --upgrade -r requirements.txt
```
Now change and adapt [Argus' settings](#settings-in-argus) according to your needs.
Run the initial Argus setup, and make note of the admin password that is generated:
```console
$ python manage.py initial_setup
******************************************************************************
Created Argus superuser "admin" with password "2S0qJbjVEew0GunL".
Please change the password via the admin interface.
******************************************************************************
```
Then run the Argus API server:
```console
$ python manage.py runserver
```
### Setup Argus using Docker Compose
Download the source code first.
```console
$ git clone https://github.com/Uninett/Argus.git
$ cd Argus
```
Running Argus with Docker Compose is as simple as
```console
$ docker compose up
```
Run the initial Argus setup, and make note of the admin password that is generated:
```console
$ docker compose exec api django-admin initial_setup
******************************************************************************
Created Argus superuser "admin" with password "ns6bfoKquW12koIP".
Please change the password via the admin interface.
******************************************************************************
```
You will find Argus running at http://localhost:8000/.
## Settings in Argus
Site-specific settings can either be set using environment variables, using a
`settings.py` file, or a combination of both.
For more information on both methods and a list of the settings, consult the
documentation section on
[site-specific settings](http://argus-server.rtfd.io/en/latest/site-specific-settings.html).
## Running Argus in development
### Step 1: Installation
You can use Docker Compose to conveniently setup a complete dev environment for Argus,
including PostgreSQL. Instructions
[are provided above](#setup-argus-using-docker-compose).
To do a manual install instead, follow these steps.
Download the source code first.
```console
$ git clone https://github.com/Uninett/Argus.git
$ cd Argus
```
We recommend using virtualenv or virtaulenvwrapper to create
a place to stash Argus' dependencies.
Create and activate a Python virtual environment.
```console
$ python -m venv venv
$ source venv/bin/activate
```
Install Argus' requirements into the virtual env.
```console
$ pip install -r requirements-django42.txt
$ pip install -r requirements/dev.txt
```
### Step 2: Setting environment variables and Django settings
Copy the `cmd.sh-template` to `cmd.sh` and make it executable
```console
$ cp cmd.sh-template cmd.sh
$ chmod u+x cmd.sh
```
Now set the environment variables in the file using an editor.
Required settings in `cmd.sh` are
- `DATABASE_URL`,
- `DJANGO_SETTINGS_MODULE` and
- `SECRET_KEY`.
The `DATAPORTEN` variables are optional. Refer to the dataporten section of
[setting site-specific settings](http://argus-server.rtfd.io/en/latest/site-specific-settings.html) for details.
`DJANGO_SETTINGS_MODULE` can be set to `argus.site.settings.dev`.
If you need more complex settings than environment variables and ``cmd.sh`` can provide,
we recommend having a `localsettings.py` in the same directory as `manage.py` with any
overrides.
Refer to the [development notes](http://argus-server.rtfd.io/en/latest/development.html) for further details and
useful hints on managing Argus in development mode.
#### Settings for old frontend
See https://argus-server.erfd.io/en/latest/reference/react-frontend.html
#### Settings for new frontend
See http://argus-server.rtfd.io/en/latest/reference/htmx-frontend.html
### Step 3: Run Argus in development
Afterwards, run the initial Argus setup and start the server.
```console
$ python manage.py initial_setup
$ python manage.py runserver
```
You will find Argus running at http://localhost:8000/.
### Code style
Argus uses [ruff](https://docs.astral.sh/ruff/) as a Python source code
formatter and linter and [djLint](https://djlint.com/) as an HTML formatter and
linter. Ruff and djLint will automatically install with the
[dev requirements](requirements/dev.txt).
A pre-commit hook will format new code automatically before committing.
To enable this pre-commit hook, run
```console
$ pre-commit install
```
## Running tests
Given that Argus is installed and configured as described above,
this command is the most basic option to run the tests.
```console
$ python manage.py test
```
If you have installed `tox`, the following command will
test Argus code against several Django versions, several Python versions, and
automatically compute code coverage.
```console
$ tox
```
An [HTML coverage report](htmlcov/index.html) will be generated.
Refer to the [tox.ini](tox.ini) file for further options.
## How to do maintenance
See [MAINTAINING.rst](MAINTAINING.rst).