almet/argos
1
0
Fork 0
mirror of https://framagit.org/framasoft/framaspace/argos.git synced 2025-04-28 18:02:41 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

📝 — Improve documentation

Browse source
This commit is contained in:
Luc Didry 2024-06-24 16:12:50 +02:00
parent 09a858794d
commit b85d7e90a8
No known key found for this signature in database
GPG key ID: EA868E12D0257E3C
7 changed files with 121 additions and 80 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
argos/commands.py
View file

@ -61,16 +61,17 @@ def cli():
@cli.group()
def server():
pass
"""Commands for managing server, server’s configuration and users"""
@server.group()
def user():
pass
"""User management"""
@cli.command()
def version():
"""Prints Argos’ version and exits"""
click.echo(VERSION)
@ -93,7 +94,7 @@ def version():
type=click.Choice(logging.LOG_LEVELS, case_sensitive=False),
)
def agent(server_url, auth, max_tasks, wait_time, log_level):
"""Get and run tasks to the provided server. Will wait for new tasks.
"""Get and run tasks for the provided server. Will wait for new tasks.
Usage: argos agent https://argos.example.org "auth-token-here"
@ -536,7 +537,7 @@ async def generate_token():
@server.command()
@coroutine
async def generate_config():
"""Output an example config file.
"""Output a self-documented example config file.
\b
Redirect the output to a file to save it:

10
argos/config-example.yaml
View file

@ -13,9 +13,13 @@ general:
# to get a good string for cookie_secret, run:
# openssl rand -hex 32
cookie_secret: "foo_bar_baz"
frequency: "1m" # Run checks every minute.
# Default delay for checks.
# Can be superseeded in domain configuration.
# For ex., to run checks every minute:
frequency: "1m"
# Which way do you want to be warned when a check goes to that severity?
# "local" emits a message in the server log
# You’ll need to configure mail and gotify below to be able to use them here.
alerts:
ok:
- local
@ -25,6 +29,7 @@ general:
- local
unknown:
- local
# Mail configuration is quite straight-forward
# mail:
# mailfrom: no-reply@example.org
# host: 127.0.0.1
@ -37,6 +42,8 @@ general:
# addresses:
# - foo@admin.example.org
# - bar@admin.example.org
# Create an app on your Gotify server and put its token here
# See https://gotify.net/ for details about Gotify
# gotify:
# - url: https://example.org
# tokens:
@ -71,6 +78,7 @@ websites:
checks:
- status-is: 401
- domain: "https://munin.example.org"
frequency: "20m"
paths:
- path: "/"
checks:

4
argos/server/main.py
View file

@ -93,6 +93,10 @@ def setup_database(appli):
def create_manager(cookie_secret):
if cookie_secret == "foo_bar_baz":
logger.warning(
"You should change the cookie_secret secret in your configuration file."
)
return LoginManager(
cookie_secret,
"/login",

54
docs/cli.md
View file

@ -26,9 +26,9 @@ Options:
--help Show this message and exit.
Commands:
agent Get and run tasks to the provided server.
server
version
agent Get and run tasks for the provided server.
server Commands for managing server, server’s configuration and users
version Prints Argos’ version and exits
```
<!--[[[end]]]
@ -43,7 +43,7 @@ Commands:
```man
Usage: argos agent [OPTIONS] SERVER_URL AUTH
Get and run tasks to the provided server. Will wait for new tasks.
Get and run tasks for the provided server. Will wait for new tasks.
Usage: argos agent https://argos.example.org "auth-token-here"
@ -73,17 +73,19 @@ Options:
```man
Usage: argos server [OPTIONS] COMMAND [ARGS]...
Commands for managing server, server’s configuration and users
Options:
--help Show this message and exit.
Commands:
cleandb Clean the database (to run routinely)
generate-config Output an example config file.
generate-config Output a self-documented example config file.
generate-token Generate a token for agents
migrate Run database migrations
reload-config Load or reload tasks’ configuration
start Starts the server (use only for testing or development!)
user
user User management
watch-agents Watch agents (to run routinely)
```
@ -222,7 +224,29 @@ Options:
<!--[[[end]]]
-->
### Server generate-token command
### Server generate-config
<!--
.. [[[cog
help(["server", "generate-config", "--help"])
.. ]]] -->
```man
Usage: argos server generate-config [OPTIONS]
Output a self-documented example config file.
Redirect the output to a file to save it:
argos server generate-config > /etc/argos/config.yaml
Options:
--help Show this message and exit.
```
<!--[[[end]]]
-->
### Server generate-token
<!--
.. [[[cog
@ -257,6 +281,8 @@ You can manage users only through CLI.
```man
Usage: argos server user [OPTIONS] COMMAND [ARGS]...
User management
Options:
--help Show this message and exit.
@ -273,7 +299,7 @@ Commands:
<!--[[[end]]]
-->
### Add user
#### Add user
<!--
.. [[[cog
@ -296,7 +322,7 @@ Options:
<!--[[[end]]]
-->
### Change the password of a user
#### Change the password of a user
<!--
.. [[[cog
@ -319,7 +345,7 @@ Options:
<!--[[[end]]]
-->
### Delete a user
#### Delete a user
<!--
.. [[[cog
@ -341,7 +367,7 @@ Options:
<!--[[[end]]]
-->
### Disable a user
#### Disable a user
Disabling a user prevents the user to login and access Argos’ web interface but its credentials are still stored in Argos’ database.
@ -365,7 +391,7 @@ Options:
<!--[[[end]]]
-->
### Enable a user
#### Enable a user
Enabling a user prevents the user to login and access Argos’ web interface.
@ -391,7 +417,7 @@ Options:
<!--[[[end]]]
-->
### List all users
#### List all users
Show all accounts, with their status (enabled or disabled).
@ -414,7 +440,7 @@ Options:
<!--[[[end]]]
-->
### Test the password of a user
#### Test the password of a user
You can verify that you have the right password for a user with the following command:

3
docs/configuration.md
View file

@ -2,8 +2,7 @@
Argos uses a simple YAML configuration file to define the server’s configuration, the websites to monitor and the checks to run on these websites.
Here is a simple configuration file:
Here is a simple self-documented configuration file, which you can get with [`argos server generate-config`](cli.md#server-generate-config):
```{literalinclude} ../conf/config-example.yaml
---

40
docs/installation/getting-started.md
View file

@ -78,7 +78,7 @@ argos 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.
Please note that the only supported database engines are SQLite for development and [PostgreSQL](postgresql.md) for production.
## Apply migrations to database
@ -98,6 +98,23 @@ Populate the database with the tasks:
argos 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:
```bash
argos server generate-token
```
Add the token in the configuration file, in the following setting:
```yaml
service:
secrets:
- "auth-token"
```
## Starting the server
Then you can start the server:
@ -142,23 +159,6 @@ See <https://fastapi.tiangolo.com/deployment/manually/#asgi-servers> (but Gunico
See [here](../deployment/systemd.md#server) for a systemd service example and [here](../deployment/nginx.md) for a nginx configuration example.
## 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.
@ -170,7 +170,7 @@ 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.
You have to run cleaning task periodically. `argos 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:
@ -182,7 +182,7 @@ Here is a crontab example, which will clean the db each hour:
## 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.
In order to be sure that agents are up and communicate with the server, you can periodically run the `argos server watch-agents` command.
Here is a crontab example, which will check the agents every 5 minutes:

7
docs/installation/tl-dr.md
View file

@ -14,7 +14,7 @@ python3 -m venv venv
source venv/bin/activate
pip install argos-monitoring
argos server generate-config |
sed -e "s@production@test@" \
sed -e "s@production@dev@" \
-e "s@url: .postgresql.*@url: \"sqlite:////tmp/argos.db\"@" > argos-config.yaml
argos server migrate
ARGOS_TOKEN=$(argos server generate-token)
@ -149,7 +149,10 @@ systemctl status argos-server.service argos-agent.service
If all works well, you have to put some cron tasks in `argos` crontab:
```bash
echo -e "*/10 * * * * /opt/argos/venv/bin/argos server cleandb --max-lock-seconds 120 --max-results 1200\n*/10 * * * * /opt/argos/venv/bin/argos server watch-agents --time-without-agent 10" | crontab -u argos -
cat <<EOF | crontab -u argos -
*/10 * * * * /opt/argos/venv/bin/argos server cleandb --max-lock-seconds 120 --max-results 1200
*/10 * * * * /opt/argos/venv/bin/argos server watch-agents --time-without-agent 10
EOF
```
See the [this page](../deployment/nginx.md) for using Nginx as reverse proxy.