diff --git a/Makefile b/Makefile index 248d8db..02b8e71 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ pylint: venv ## Runs pylint on the code venv/bin/pylint argos pylint-alembic: venv ## Runs pylint on alembic migration files venv/bin/pylint --disable invalid-name,no-member alembic/versions/*.py -lint: djlint pylint +lint: djlint pylint pylint-alembic ruff help: @python3 -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) diff --git a/docs/api.md b/docs/api.md index 2260d14..7fe1b2a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -10,6 +10,8 @@ To access the API, you need to pass an authentication token in the `Authorizatio "Authorization": "Bearer " + token ``` +See the [CLI documentation](cli.md#server-generate-token-command) to generate tokens. + ## Endpoints You can also have access to the Swagger API documentation at `https:///docs`, and the ReDoc documentation at `https:///redoc`. diff --git a/docs/capture.png b/docs/capture.png deleted file mode 100644 index 5a65fcd..0000000 Binary files a/docs/capture.png and /dev/null differ diff --git a/docs/dashboard.jpg b/docs/dashboard.jpg new file mode 100644 index 0000000..c28a28e Binary files /dev/null and b/docs/dashboard.jpg differ diff --git a/docs/developer/dependencies.md b/docs/developer/dependencies.md new file mode 100644 index 0000000..633d519 --- /dev/null +++ b/docs/developer/dependencies.md @@ -0,0 +1,11 @@ +# Installing for development + +To install all what you need to develop on Argos, do: + +```bash +git clone https://framagit.org/framasoft/framaspace/argos.git +cd argos +make develop +``` + +It will create a virtualenv and install all the needed dependencies in it. diff --git a/docs/developer/tests.md b/docs/developer/tests.md new file mode 100644 index 0000000..a7d9f1a --- /dev/null +++ b/docs/developer/tests.md @@ -0,0 +1,21 @@ +# Tests and linting + +## Tests + +To launch the tests suite: +```bash +make tests +``` + +## Linting + +There is 4 lintings checks: +- `make djlint` will check the linting of the HTML templates +- `make pylint` will check the linting of Argos source code +- `make pylint-alembic` will check the linting of Alembic’s migrations files +- `make ruff` will check the linting of all files + +You can launch all of them with: +```bash +make lint +``` diff --git a/docs/domains.jpg b/docs/domains.jpg new file mode 100644 index 0000000..0c00424 Binary files /dev/null and b/docs/domains.jpg differ diff --git a/docs/index.md b/docs/index.md index bbcb6d1..d72c8f8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,33 +10,20 @@ Test how your websites respond to external checks, get notified when something g - A **Website** allows to navigate the results of the checks. - **HTTP API**: An HTTP API is exposed to get the results of the checks. +![Dashboard](dashboard.jpg) -![Argos web interface](capture.png) - -## Installation - -```{code-block} bash -pip install argos-monitoring -argos server start -argos agent http://localhost:8000 "" -``` - -```{literalinclude} ../config-example.yaml ---- -caption: config.yaml ---- -``` +![Domains list](domains.jpg) ## Next ::::{grid} 2 -:::{grid-item-card} Getting started +:::{grid-item-card} Installation :link: installation/getting-started.html The best way to get started with argos. ::: :::{grid-item-card} Developper docs :link: developer/overview.html -You want to know more about the internals ?. +You want to know more about the internals ? ::: :::: @@ -69,9 +56,11 @@ checks :caption: Developer docs :hidden: developer/overview +developer/dependencies developer/new-check developer/models developer/migrations +developer/tests developer/projects changelog ``` diff --git a/docs/installation/getting-started.md b/docs/installation/getting-started.md index 374899a..a71ff65 100644 --- a/docs/installation/getting-started.md +++ b/docs/installation/getting-started.md @@ -15,17 +15,53 @@ source venv/bin/activate pip install -e . ``` + + ## Configure +### Configure the checks + The quickest way to get started is to copy the `config-example.yaml` file and edit it: ```bash cp config-example.yaml config.yaml ``` + + You can read more about the configuration in the [configuration section](../configuration.md). -## Starting the server +### Configure the server Environment variables are used to configure the server. You can also put them in an `.env` file: @@ -37,6 +73,8 @@ caption: .env Please note that the only supported database engines are SQLite for development and PostgreSQL for production. +## Starting the server + Then you can start the server: ```bash @@ -45,12 +83,30 @@ argos server start The server reads the `yaml` file at startup, and populates the tasks queue with the checks defined in the configuration. +## 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. +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 "" +argos agent http://localhost:8000 "auth-token" ``` ## Cleaning the database @@ -61,6 +117,6 @@ 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 locks the tasks for 1 hour +# Keeps 10 results per task, and remove tasks’ locks older than 1 hour 7 * * * * argos server cleandb --max-results 10 --max-lock-seconds 3600 ``` diff --git a/docs/installation/postgresql.md b/docs/installation/postgresql.md index 89fe344..97ea49e 100644 --- a/docs/installation/postgresql.md +++ b/docs/installation/postgresql.md @@ -1,10 +1,4 @@ -# Use with PostgreSQL - -If you intend to use argos with Postgresql, which is recommended for production, you can install it with the following commands: - -```bash -pip install -e ".[postgres]" -``` +# Install and configure PostgreSQL Here are a few steps for you to install PostgreSQL on your system: diff --git a/pyproject.toml b/pyproject.toml index 6de83f8..58495b9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,8 +20,10 @@ dependencies = [ "alembic>=1.13.0,<1.14", "click>=8.1,<9", "fastapi>=0.103,<0.104", + "gunicorn>=21.2,<22", "httpx>=0.25,<1", "Jinja2>=3.0,<4", + "psycopg2-binary>=2.9,<3", "pydantic[email]>=2.4,<3", "pydantic-settings>=2.0,<3", "pyyaml>=6.0,<7", @@ -30,7 +32,6 @@ dependencies = [ "sqlalchemy-utils>=0.41,<1", "tenacity>=8.2,<9", "uvicorn>=0.23,<1", - "gunicorn>=21.2,<22", ] [project.optional-dependencies] @@ -47,9 +48,6 @@ dev = [ "ruff==0.1.5,<1", "sphinx-autobuild", ] -postgres = [ - "psycopg2-binary>=2.9,<3", -] docs = [ "cogapp", "myst-parser>=2.0,<3",