mirror of
https://framagit.org/framasoft/framaspace/argos.git
synced 2025-04-28 18:02:41 +02:00
e2402ac190
Argos will first try the given config file (given either with `--config` or with `ARGOS_YAML_FILE` env var), then `argos-config.yaml`, then `/etc/argos/config.yaml`.
172 lines
4.4 KiB
Markdown
172 lines
4.4 KiB
Markdown
# Installation
|
||
|
||
NB: if you want a quick-installation guide, we [got you covered](tl-dr.md).
|
||
|
||
## Requirements
|
||
|
||
- Python 3.11+
|
||
- PostgreSQL 13+ (for production)
|
||
|
||
## Install with pip
|
||
|
||
```bash
|
||
pip install argos-monitoring
|
||
```
|
||
|
||
You may want to install Argos in a virtualenv:
|
||
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install argos-monitoring
|
||
```
|
||
|
||
For production, we recommend the use of [Gunicorn](https://gunicorn.org/), which you can install at the same time as Argos:
|
||
|
||
```bash
|
||
pip install argos-monitoring[gunicorn]
|
||
```
|
||
|
||
## Install from sources
|
||
|
||
Once you got the source locally, create a virtualenv and install the dependencies:
|
||
|
||
```bash
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install -e .
|
||
```
|
||
|
||
## Configure
|
||
|
||
The quickest way to get started is to generate the configuration file from argos and edit it:
|
||
|
||
```bash
|
||
argos server generate-config > argos-config.yaml
|
||
```
|
||
|
||
You can read more about the configuration in the [configuration section](../configuration.md).
|
||
|
||
### Configure the server
|
||
|
||
Environment variables are used to configure the server. You can also put them in an `.env` file:
|
||
|
||
```{literalinclude} ../../conf/.env.example
|
||
---
|
||
caption: .env
|
||
---
|
||
```
|
||
|
||
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:
|
||
|
||
```bash
|
||
argos server migrate
|
||
```
|
||
|
||
## Inject tasks into the database
|
||
|
||
Argos keeps tasks’ configuration in database, take from the config file.
|
||
|
||
Populate the database with the tasks:
|
||
|
||
```bash
|
||
argos server reload-config
|
||
```
|
||
|
||
## Starting the server
|
||
|
||
Then you can start the server:
|
||
|
||
```bash
|
||
argos server start
|
||
```
|
||
|
||
The server reads the `yaml` file at startup, and populates the tasks queue with the checks defined in the configuration.
|
||
|
||
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](https://gunicorn.org/) to start the server.
|
||
|
||
To install Gunicorn in the virtualenv, if you didn’t already install Argos that way:
|
||
|
||
```bash
|
||
pip install argos-monitoring[gunicorn]
|
||
```
|
||
|
||
To start the server:
|
||
|
||
```bash
|
||
gunicorn "argos.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`:
|
||
|
||
```bash
|
||
gunicorn "argos.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).
|
||
|
||
## 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:
|
||
```bash
|
||
argos server generate-token
|
||
```
|
||
|
||
Add the token in the configuration file, in the following setting:
|
||
|
||
```yaml
|
||
service:
|
||
secrets:
|
||
- "auth-token"
|
||
```
|
||
|
||
## 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.
|
||
|
||
```bash
|
||
argos agent http://localhost:8000 "auth-token"
|
||
```
|
||
|
||
## Cleaning the database
|
||
|
||
You also have to run cleaning tasks periodically. `argos server clean --help` will give you more information on how to do that.
|
||
|
||
Here is a crontab example, which will clean the db each hour:
|
||
|
||
```bash
|
||
# Run the cleaning tasks every hour (at minute 7)
|
||
# Keeps 10 results per task, and remove tasks’ locks older than 1 hour
|
||
7 * * * * argos 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 run periodically the `argos server watch-agents` command.
|
||
|
||
Here is a crontab example, which will check the agents every 5 minutes:
|
||
|
||
```bash
|
||
*/5 * * * * argos server watch-agents --time-without-agent 10
|
||
```
|
||
|
||
Check the documentation of the command with `argos server watch-agents --help`
|