mirror of
https://framagit.org/framasoft/framaspace/argos.git
synced 2025-04-28 18:02:41 +02:00
📝 — Improve documentation
This commit is contained in:
Luc Didry
parent
09a858794d
commit
b85d7e90a8
7 changed files with 121 additions and 80 deletions
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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,23 +29,26 @@ general:
|
|||
- local
|
||||
unknown:
|
||||
- local
|
||||
# mail:
|
||||
# mailfrom: no-reply@example.org
|
||||
# host: 127.0.0.1
|
||||
# port: 25
|
||||
# ssl: False
|
||||
# starttls: False
|
||||
# auth:
|
||||
# login: foo
|
||||
# password: bar
|
||||
# addresses:
|
||||
# - foo@admin.example.org
|
||||
# - bar@admin.example.org
|
||||
# gotify:
|
||||
# - url: https://example.org
|
||||
# tokens:
|
||||
# - foo
|
||||
# - bar
|
||||
# Mail configuration is quite straight-forward
|
||||
# mail:
|
||||
# mailfrom: no-reply@example.org
|
||||
# host: 127.0.0.1
|
||||
# port: 25
|
||||
# ssl: False
|
||||
# starttls: False
|
||||
# auth:
|
||||
# login: foo
|
||||
# password: bar
|
||||
# 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:
|
||||
# - foo
|
||||
# - bar
|
||||
|
||||
service:
|
||||
secrets:
|
||||
|
|
@ -56,25 +63,26 @@ ssl:
|
|||
|
||||
# It's also possible to define the checks in another file
|
||||
# with the include syntax:
|
||||
#
|
||||
# websites: !include websites.yaml
|
||||
#
|
||||
# websites: !include websites.yaml
|
||||
#
|
||||
websites:
|
||||
- domain: "https://mypads.example.org"
|
||||
paths:
|
||||
- path: "/mypads/"
|
||||
checks:
|
||||
- status-is: 200
|
||||
- body-contains: '<div id= "mypads"></div>'
|
||||
- ssl-certificate-expiration: "on-check"
|
||||
- path: "/admin/"
|
||||
checks:
|
||||
- status-is: 401
|
||||
- domain: "https://munin.example.org"
|
||||
paths:
|
||||
- path: "/"
|
||||
checks:
|
||||
- status-is: 301
|
||||
- path: "/munin/"
|
||||
checks:
|
||||
- status-is: 401
|
||||
- domain: "https://mypads.example.org"
|
||||
paths:
|
||||
- path: "/mypads/"
|
||||
checks:
|
||||
- status-is: 200
|
||||
- body-contains: '<div id= "mypads"></div>'
|
||||
- ssl-certificate-expiration: "on-check"
|
||||
- path: "/admin/"
|
||||
checks:
|
||||
- status-is: 401
|
||||
- domain: "https://munin.example.org"
|
||||
frequency: "20m"
|
||||
paths:
|
||||
- path: "/"
|
||||
checks:
|
||||
- status-is: 301
|
||||
- path: "/munin/"
|
||||
checks:
|
||||
- status-is: 401
|
||||
|
|
|
|||
|
|
@ -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
54
docs/cli.md
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue