📝 — Improve documentation

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:

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,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:

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",

docs/cli.md

@@ -26,9 +26,9 @@ Options:
   --help  Show this message and exit.
 
 Commands:
-  agent    Get and run tasks to the provided server.
+  agent    Get and run tasks for the provided server.
-  server
+  server   Commands for managing server, server’s configuration and users
-  version
+  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:
 

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
 ---

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 <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:
 

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 <<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.