Skip to main content

Argus is an alert aggregator for monitoring systems

Project description

Argus

test badge codecov badge Ruff djLint docs badge

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 for more details.

See also the the Python client library.

[!IMPORTANT]

  • API v1 has been removed. API v2 is the new stable. Support for API v1 was dropped in version 2.0 of argus-server. Please upgrade your glue services!
  • Support for the REACT frontend was 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 5.2
  • pip
  • PostgreSQL 14+

Optional requirements

  • Docker and Docker Compose to run Argus in Docker. This will also run a PostgreSQL server for you.

Optional: Frontend

You need to have the frontend-specific dependencies installed.

pip install argus-server[htmx]

will do it.

Optional: Federated login for frontend

See Federated Login @ Read The Docs or local copy of Federated Login docs.

Install Argus using pip

You can also install Argus with pip via PyPI. The package name is argus-server:

$ 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:

$ 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:

$ pip install -c constraints.txt --upgrade -r requirements.txt

Now change and adapt Argus' settings according to your needs.

Run the initial Argus setup, and make note of the admin password that is generated:

$ 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:

$ python manage.py runserver

Setup Argus using Docker Compose

Download the source code first.

$ git clone https://github.com/Uninett/Argus.git
$ cd Argus

Running Argus with Docker Compose is as simple as

$ docker compose up

Run the initial Argus setup, and make note of the admin password that is generated:

$ 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.

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.

To do a manual install instead, follow these steps.

Download the source code first.

$ 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.

$ python -m venv venv
$ source venv/bin/activate

Install Argus' requirements into the virtual env.

$ pip install -r requirements-django52.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

$ 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.

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 for further details and useful hints on managing Argus in development mode.

Settings for the frontend

See https://argus-server.readthedocs.io/en/latest/reference/htmx-frontend.html.

Step 3: Run Argus in development

Afterwards, run the initial Argus setup and start the server.

$ python manage.py initial_setup
$ python manage.py runserver

You will find Argus running at http://localhost:8000/.

Code style

Argus uses ruff as a Python source code formatter and linter and djLint as an HTML formatter and linter. Ruff and djLint will automatically install with the dev requirements.

A pre-commit hook will format new code automatically before committing. To enable this pre-commit hook, run

$ 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.

$ 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.

$ tox

An HTML coverage report will be generated. Refer to the tox.ini file for further options.

Magical branches

Do not ever remove these

  • master
  • argus-demo
  • stable/SOMETHING

The last branch-type is for backporting bugfixes and similar to older releases, bypassing master if necessary.

How to do maintenance

See MAINTAINING.rst.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

argus_server-2.1.0.tar.gz (582.7 kB view details)

Uploaded Source

Built Distribution

argus_server-2.1.0-py3-none-any.whl (307.5 kB view details)

Uploaded Python 3

File details

Details for the file argus_server-2.1.0.tar.gz.

File metadata

  • Download URL: argus_server-2.1.0.tar.gz
  • Upload date:
  • Size: 582.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for argus_server-2.1.0.tar.gz
Algorithm Hash digest
SHA256 7be0f870a0ed9618bab8a3eaa2cd5fa2f06062da1524c04ec16bf64a627c37b3
MD5 3370b7693c616be12a8667a4d3087daa
BLAKE2b-256 9333b3dd73ee741e5b1cae44c066c3bff2bf49916bce3c4a90d6724f56fd1d66

See more details on using hashes here.

File details

Details for the file argus_server-2.1.0-py3-none-any.whl.

File metadata

  • Download URL: argus_server-2.1.0-py3-none-any.whl
  • Upload date:
  • Size: 307.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for argus_server-2.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 72d276d0ee741a4da6d5c06ac1774872cf6234162aab24e32a1166221547db05
MD5 b6138573a600cce4f6ac5b79d944feb7
BLAKE2b-256 92d6a965a3385d1d2b46a303f2303494ffaa6a0b72aacc0689b9522424cd8778

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page