From b85d7e90a8890306a8d32142f55be3dbd48625f0 Mon Sep 17 00:00:00 2001 From: Luc Didry Date: Mon, 24 Jun 2024 16:12:50 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20=E2=80=94=20Improve=20documentat?= =?UTF-8?q?ion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- argos/commands.py | 9 +-- argos/config-example.yaml | 84 +++++++++++++++------------- argos/server/main.py | 4 ++ docs/cli.md | 54 +++++++++++++----- docs/configuration.md | 3 +- docs/installation/getting-started.md | 40 ++++++------- docs/installation/tl-dr.md | 7 ++- 7 files changed, 121 insertions(+), 80 deletions(-) diff --git a/argos/commands.py b/argos/commands.py index 9eb9700..0fc1491 100644 --- a/argos/commands.py +++ b/argos/commands.py @@ -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: diff --git a/argos/config-example.yaml b/argos/config-example.yaml index aed2c10..41f00d6 100644 --- a/argos/config-example.yaml +++ b/argos/config-example.yaml @@ -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: '
' - - 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: '
' + - 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 diff --git a/argos/server/main.py b/argos/server/main.py index d1f3b5f..898b202 100644 --- a/argos/server/main.py +++ b/argos/server/main.py @@ -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", diff --git a/docs/cli.md b/docs/cli.md index 2d934ff..83a98f3 100644 --- a/docs/cli.md +++ b/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 ``` -### Server generate-token command +### Server generate-config + + + +```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. +``` + + + +### Server generate-token -### Add user +#### Add user -### Change the password of a user +#### Change the password of a user -### Delete a user +#### Delete a user -### 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: -### Enable a user +#### Enable a user Enabling a user prevents the user to login and access Argos’ web interface. @@ -391,7 +417,7 @@ Options: -### List all users +#### List all users Show all accounts, with their status (enabled or disabled). @@ -414,7 +440,7 @@ Options: -### 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: diff --git a/docs/configuration.md b/docs/configuration.md index 4c819a4..576c55c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 --- diff --git a/docs/installation/getting-started.md b/docs/installation/getting-started.md index b9876eb..65fae33 100644 --- a/docs/installation/getting-started.md +++ b/docs/installation/getting-started.md @@ -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 (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: diff --git a/docs/installation/tl-dr.md b/docs/installation/tl-dr.md index 88c1981..26b35b6 100644 --- a/docs/installation/tl-dr.md +++ b/docs/installation/tl-dr.md @@ -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 <