argos/docs/installation/getting-started.md

Installation

NB: if you want a quick-installation guide, we got you covered.

Requirements

• Python 3.11+
• PostgreSQL 13+ (for production)

Recommendation

Create a dedicated user for argos:

adduser --home /opt/argos --disabled-login --disabled-password --system argos

Do all the manipulations below in /opt/argos/, with the user argos. Either use sudo or login as argos with the following command:

su argos -s /bin/bash

Install with pip

pip install argos-monitoring

You may want to install Argos in a virtualenv:

python3 -m venv venv
source venv/bin/activate
pip install argos-monitoring

For production, we recommend the use of Gunicorn, which you can install at the same time as Argos:

pip install "argos-monitoring[gunicorn]"

Install from sources

Once you got the source locally, create a virtualenv and install the dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -e .

To install gunicorn, use pip install -e ".[gunicorn]" instead of pip install -e .

Configure

The quickest way to get started is to generate the configuration file from argos and edit it:

argos-monitoring server generate-config > argos-config.yaml

You can read more about the configuration in the configuration section.

For production, we suggest to put your config in /etc/argos/config.yaml and restricts the file’s permissions. As root:

mkdir /etc/argos
chown argos: /etc/argos
chmod 700 /etc/argos

Then, as argos:

argos-monitoring server generate-config > /etc/argos/config.yaml
chmod 600 /etc/argos/config.yaml

Please note that the only supported database engines are SQLite for development and PostgreSQL for production.

Apply migrations to database

Create the schema in the database with:

argos-monitoring server migrate

Inject tasks into the database

Argos keeps tasks’ configuration in database, taken from the config file.

Populate the database with the tasks:

argos-monitoring server reload-config

Generating a token

The agent needs an authentication token to be able to communicate with the server.

You can generate an authentication token with the following command:

argos-monitoring server generate-token

Add the token in the configuration file, in the following setting:

service:
  secrets:
    - "auth-token"

Starting the server

Then you can start the server:

argos-monitoring server start

This way to start the server is not suitable for production, use it only for developing or testing.

Starting the server for production

For production, you can use Gunicorn to start the server.

To install Gunicorn in the virtualenv, if you didn’t already install Argos that way:

pip install "argos-monitoring[gunicorn]"

To start the server:

gunicorn "argos_monitoring.server.main:get_application()" -k uvicorn.workers.UvicornWorker

There is some gunicorn’s options that you should use:

• -w INT, --workers INT: the number of worker processes for handling requests. Default is 1.
• -b ADDRESS, --bind ADDRESS: the socket to bind. Default is 127.0.0.1:8000.
• --forwarded-allow-ips STRING: front-end's IPs from which allowed to handle set secure headers as a comma-separated list. Default is 127.0.0.1.

So, to start the server with 4 workers while listening to 127.0.0.1:8001:

export ARGOS_YAML_FILE=/etc/argos/config.yaml
gunicorn "argos_monitoring.server.main:get_application()" -k uvicorn.workers.UvicornWorker -w 4 -b 127.0.0.1:8001

Gunicorn has a lot of other options, have a look at gunicorn --help.

Argos uses FastAPI, so you can use other ways to start the server. See https://fastapi.tiangolo.com/deployment/manually/#asgi-servers (but Gunicorn is recommended).

See here for a systemd service example and here for a nginx configuration example.

Running the agent

You can run the agent on the same machine as the server, or on a different machine. The only requirement is that the agent can reach the server through HTTP or HTTPS.

argos-monitoring agent http://localhost:8000 "auth-token"

Cleaning the database

You have to run cleaning task periodically. argos-monitoring server cleandb --help will give you more information on how to do that.

Here is a crontab example, which will clean the db each hour:

# Run the cleaning tasks every hour (at minute 7)
# Keeps 10 results per task, and remove tasks’ locks older than 1 hour
7 * * * * argos-monitoring server cleandb --max-results 10 --max-lock-seconds 3600

Watch the agents

In order to be sure that agents are up and communicate with the server, you can periodically run the argos-monitoring server watch-agents command.

Here is a crontab example, which will check the agents every 5 minutes:

*/5 * * * * argos-monitoring server watch-agents --time-without-agent 10

Check the documentation of the command with argos-monitoring server watch-agents --help