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

🔀 Merge branch 'fix-43' into 'develop'

Browse source 
📝 — TL;DR documentation (fix #43)

See merge request framasoft/framaspace/argos!50
This commit is contained in:
Luc Didry 2024-06-10 09:01:21 +00:00
commit 4f6207509b
11 changed files with 206 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
CHANGELOG.md
View file

@ -6,6 +6,7 @@
- 🔊 — Add level of log before the log message
— 🔊 — Add a warning messages in the logs if there is no tasks in database. (fix #41)
- ✨ — Add command to generate example configuration (fix #38)
- 📝 — Improve documentation
## 0.1.1

5
conf/default-argos-agent Normal file
View file

@ -0,0 +1,5 @@
ARGOS_AGENT_TOKEN=Secret
ARGOS_AGENT_SERVER_URL=http://127.0.0.1:8000
ARGOS_AGENT_LOGLEVEL=WARNING
ARGOS_AGENT_MAX_TASKS=20
ARGOS_AGENT_WAIT_TIME=10

6
conf/default-argos-server Normal file
View file

@ -0,0 +1,6 @@
ARGOS_YAML_FILE="/etc/argos/config.yaml"
ARGOS_DATABASE_URL="postgresql://argos:THE_DB_PASSWORD@localhost/argos"
ARGOS_SERVER_WORKERS=4
ARGOS_SERVER_SOCKET=127.0.0.1:8000
# Comma separated list of IP addresses of the web proxy (usually Nginx)
ARGOS_SERVER_FORWARDED_ALLOW_IPS=127.0.0.1

16
conf/systemd-agent.service
View file

@ -5,17 +5,13 @@ Requires=network.target
After=network.target
[Service]
User=www-data
Environment="ARGOS_AGENT_TOKEN=Secret"
Environment="ARGOS_AGENT_SERVER_URL=http://127.0.0.1:8000"
WorkingDirectory=/var/www/argos/
ExecStart=/var/www/argos/venv/bin/argos agent --max-tasks 20 --wait-time 10 --log-level DEBUG
User=argos
EnvironmentFile=/etc/default/argos-agent
WorkingDirectory=/opt/argos/
ExecStart=/opt/argos/venv/bin/argos agent --max-tasks $ARGOS_AGENT_MAX_TASKS \
--wait-time $ARGOS_AGENT_WAIT_TIME \
--log-level $ARGOS_AGENT_LOGLEVEL
SyslogIdentifier=argos-agent
[Install]
WantedBy=multi-user.target
# NB: it may be better to
# - use a dedicated user
# - use a EnvironmentFile=/etc/default/argos-agent in order to enable configuration
# changes without doing a systemctl daemon-reload

23
conf/systemd-server.service
View file

@ -6,19 +6,18 @@ After=network.target postgresql.service
PartOf=postgresql.service
[Service]
User=www-data
WorkingDirectory=/var/www/argos/
Environment="ARGOS_SERVER_WORKERS=4"
Environment="ARGOS_SERVER_SOCKET=127.0.0.1:8000"
ExecStartPre=/var/www/argos/venv/bin/argos server migrate
ExecStartPre=/var/www/argos/venv/bin/argos server reload-config
ExecStart=/var/www/argos/venv/bin/gunicorn "argos.server.main:get_application()" -w $ARGOS_SERVER_WORKERS -k uvicorn.workers.UvicornWorker -b $ARGOS_SERVER_SOCKET
ExecReload=/var/www/argos/venv/bin/argos server reload
User=argos
WorkingDirectory=/opt/argos/
EnvironmentFile=/etc/default/argos-server
ExecStartPre=/opt/argos/venv/bin/argos server migrate
ExecStartPre=/opt/argos/venv/bin/argos server reload-config
ExecStart=/opt/argos/venv/bin/gunicorn "argos.server.main:get_application()" \
--workers $ARGOS_SERVER_WORKERS \
--worker-class uvicorn.workers.UvicornWorker \
--bind $ARGOS_SERVER_SOCKET \
--forwarded-allow-ips $ARGOS_SERVER_FORWARDED_ALLOW_IPS
ExecReload=/opt/argos/venv/bin/argos server reload-config
SyslogIdentifier=argos-server
[Install]
WantedBy=multi-user.target
# NB: it may be better to
# - use a EnvironmentFile=/etc/default/argos-server in order to enable configuration
# changes without doing a systemctl daemon-reload

11
docs/cli.md
View file

@ -77,11 +77,12 @@ Options:
--help Show this message and exit.
Commands:
cleandb Clean the database (to run routinely)
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!)
cleandb Clean the database (to run routinely)
generate-config Output an 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!)
```
<!--[[[end]]]

12
docs/deployment/systemd.md
View file

@ -4,6 +4,12 @@ Here are the systemd files that can be used to deploy the server and the agents.
## Agent
```{literalinclude} ../../conf/default-argos-agent
---
caption: /etc/default/argos-agent
---
```
```{literalinclude} ../../conf/systemd-agent.service
---
caption: /etc/systemd/system/argos-agent.service
@ -12,6 +18,12 @@ caption: /etc/systemd/system/argos-agent.service
## Server
```{literalinclude} ../../conf/default-argos-server
---
caption: /etc/default/argos-server
---
```
```{literalinclude} ../../conf/systemd-server.service
---
caption: /etc/systemd/system/argos-server.service

2
docs/faq.md
View file

@ -16,7 +16,7 @@ In one word: scalability.
While [statping-ng](https://statping-ng.github.io/) and [Uptime Kumap](https://uptime.kuma.pet/) have a similar goal than Argos, you can’t monitor thousands of web sites with them efficiently as their dashboard wants to present you the results of all of your web sites at once… and with the history of the results.
We give those solutions a try, but fetching thousand of results from the dashboard made the backend overloads.
We gave those solutions a try, but fetching thousand of results from the dashboard made the backend overloads.
## Who created Argos?

1
docs/index.md
View file

@ -38,6 +38,7 @@ cli
api
changelog
faq
installation/tl-dr
```
```{toctree}

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

@ -1,5 +1,7 @@
# Installation
NB: if you want a quick-installation guide, we [got you covered](tl-dr.md).
## Requirements
- Python 3.11+

155
docs/installation/tl-dr.md Normal file
View file

@ -0,0 +1,155 @@
# TL;DR: fast installation instructions
You want to install Argos fast? Ok, here we go.
## For testing
This is for testing only!
```bash
sudo apt install python3
mkdir /tmp/argos
cd /tmp/argos
python3 -m venv venv
source venv/bin/activate
pip install argos-monitoring
argos server generate-config > config.yaml
argos server migrate
argos server generate-token
```
Edit `argos-config.yaml`.
Add the generated token in it, as long as some real web sites to test.
Then:
```
argos server reload-config
argos server start --host 0.0.0.0 --port 8000
```
In another terminal:
```
cd /tmp/argos
source venv/bin/activate
argos agent http://127.0.0.1:8000 the_generated_token
```
Then go to `http://127.0.0.1:8000` or `http://the_IP_address_of_your_server:8000`.
## For production
```bash
apt install python3 postgresql
sudo -u postgres createuser -P argos
sudo -u postgres createdb -O argos argos
sudo -u postgres psql -c "ALTER DATABASE argos SET TIMEZONE TO 'UTC';"
adduser --home /opt/argos --disabled-login --disabled-password --system argos
cd /opt/argos
python3 -m venv venv
chown argos: -R venv
sudo -u argos bash -c "source venv/bin/activate && pip install argos-monitoring"
mkdir /etc/argos
wget https://framagit.org/framasoft/framaspace/argos/-/raw/main/conf/config-example.yaml -O /etc/argos/config.yaml
cat <<EOF > /etc/default/argos-server
ARGOS_YAML_FILE="/etc/argos/config.yaml"
ARGOS_DATABASE_URL="postgresql://argos:THE_DB_PASSWORD@localhost/argos"
ARGOS_SERVER_WORKERS=4
ARGOS_SERVER_SOCKET=127.0.0.1:8000
# Comma separated list of IP addresses of the web proxy (usually Nginx)
ARGOS_SERVER_FORWARDED_ALLOW_IPS=127.0.0.1
EOF
cat <<EOF > /etc/default/argos-agent
ARGOS_AGENT_TOKEN=Secret
ARGOS_AGENT_SERVER_URL=http://127.0.0.1:8000
ARGOS_AGENT_LOGLEVEL=WARNING
ARGOS_AGENT_MAX_TASKS=20
ARGOS_AGENT_WAIT_TIME=10
EOF
cat <<EOF > /etc/systemd/system/argos-server.service
[Unit]
Description=Argos server
Documentation=https://framasoft.frama.io/framaspace/argos/
Requires=network.target postgresql.service
After=network.target postgresql.service
PartOf=postgresql.service
[Service]
User=argos
WorkingDirectory=/opt/argos/
EnvironmentFile=/etc/default/argos-server
ExecStartPre=/opt/argos/venv/bin/argos server migrate
ExecStartPre=/opt/argos/venv/bin/argos server reload-config
ExecStart=/opt/argos/venv/bin/gunicorn "argos.server.main:get_application()" \\
--workers \$ARGOS_SERVER_WORKERS \\
--worker-class uvicorn.workers.UvicornWorker \\
--bind \$ARGOS_SERVER_SOCKET \\
--forwarded-allow-ips \$ARGOS_SERVER_FORWARDED_ALLOW_IPS
ExecReload=/opt/argos/venv/bin/argos server reload-config
SyslogIdentifier=argos-server
[Install]
WantedBy=multi-user.target
EOF
cat <<EOF > /etc/systemd/system/argos-agent.service
[Unit]
Description=Argos agent
Documentation=https://framasoft.frama.io/framaspace/argos/
Requires=network.target
After=network.target
[Service]
User=argos
EnvironmentFile=/etc/default/argos-agent
WorkingDirectory=/opt/argos/
ExecStart=/opt/argos/venv/bin/argos agent --max-tasks \$ARGOS_AGENT_MAX_TASKS \\
--wait-time \$ARGOS_AGENT_WAIT_TIME \\
--log-level \$ARGOS_AGENT_LOGLEVEL
SyslogIdentifier=argos-agent
[Install]
WantedBy=multi-user.target
EOF
chown -R argos: /etc/default/argos-* /etc/argos/
systemctl daemon-reload
```
Then, edit `/etc/default/argos-server` to put your database password in it and change the other settings to suit your needs.
Create a token for your agent :
```bash
su - argos -s /bin/bash
. /etc/default/argos-server
export ARGOS_DATABASE_URL
export ARGOS_YAML_FILE
/opt/argos/venv/bin/argos server generate-token
exit
```
Edit `/etc/default/argos-agent` to put the generated token in it and change the other settings to suit your needs.
Edit `/etc/argos/config.yaml` to configure Argos (don’t forget to add the generated token in it too).
Enable and start the server and the agent and make sure they works:
```bash
systemctl enable --now argos-server.service argos-agent.service
systemctl status argos-server.service argos-agent.service
```
If all works well, you have to put a cron task in `argos` crontab:
```bash
echo "*/10 * * * * . /etc/default/argos-server && export ARGOS_DATABASE_URL && export ARGOS_YAML_FILE && cd /opt/argos/ && /opt/argos/venv/bin/argos server cleandb --max-lock-seconds 120 --max-results 1200" | crontab -u argos -
```
See the [this page](../deployment/nginx.md) for using Nginx as reverse proxy.