Argus
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.
DEMO
Give Argus a test-run!
See https://argus-demo.uninett.no/.
The demo has notification sending turned off, and automated ticket creation is also turned off. The database is reset every 24 hours. Fake incidents are randomly generated and randomly closed.
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: Federated login for frontend
See Federated Login @ Read The Docs or local copy of Federated Login docs.
Install Argus using pip from PyPI
You can install Argus with pip via PyPI. The package name is argus-server:
$ pip install argus-server
If you are using the PyPI wheel package in production, please note: It does not use pinned dependencies. (There is no single official standard for pinned dependencies in Python as of yet.)
Install Argus from source
Download the source code first.
$ git clone https://github.com/Uninett/Argus.git
$ cd Argus
PyPI has sdists of the source if you do not want to use git.
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. The wheel
package does not contain either of these two files.
To install from the lock-file use pip:
$ pip install -c constraints.txt --upgrade -r requirements.txt
First run
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
Update pinned dependencies
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.
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 argus 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 virtualenvwrapper 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_MODULEandSECRET_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
- main
- argus-demo
- stable/SOMETHING
The last branch-type is for backporting bugfixes and similar to older releases, bypassing main if necessary.
How to do maintenance
See MAINTAINING.rst.
2 maintainers
Release files for argus-server 2.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| argus_server-2.10.0.tar.gz | 4.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| argus_server-2.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.2 MB
Release files / argus_server-2.10.0.tar.gz
| Download URL | argus_server-2.10.0.tar.gz |
|---|---|
| Size | 4.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3efe08ae60b474c18ac91720bbf30c77cea34e8727d6553be5970441f630c6e0
|
|
BLAKE2b-256 checksum How to use checksums |
2a2606329154a966a45e976663eeee3d7d59814455e7a404eecb72a6e8f78c1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / argus_server-2.10.0-py3-none-any.whl
| Download URL | argus_server-2.10.0-py3-none-any.whl |
|---|---|
| Size | 585.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d8f51be635033a0957c8060601b9d2eeebdb2fe8d7ec65d7cb7e1185a57f9334
|
|
BLAKE2b-256 checksum How to use checksums |
5f5825b62ba520a5cc21a325db1083f61f685c952b544af79d183b1530dd0580
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
