194 lines
4.4 KiB
Markdown
194 lines
4.4 KiB
Markdown
# EthicaAgent Setup Playbook
|
|
|
|
Deploy the Ethica Agent on any Linux server to push CPU, memory, disk (and more) to the Ethica.no dashboard.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8+ (pre-installed on Ubuntu 20.04+, Debian 11+, RHEL 8+)
|
|
- Root or sudo access to the target server
|
|
- A company token from the Ethica admin panel (Company → API tab)
|
|
|
|
---
|
|
|
|
## Step 1 — Get a company token
|
|
|
|
1. Log in to the Ethica admin panel
|
|
2. Go to **Companies** → select the company → **API** tab
|
|
3. Click **Generate token** if none exists
|
|
4. Copy the token — this is your `ETHICA_TOKEN`
|
|
|
|
---
|
|
|
|
## Step 2 — Deploy the agent files
|
|
|
|
```bash
|
|
# On the server (or copy via scp from your local machine):
|
|
mkdir -p /opt/ethica-agent
|
|
cd /opt/ethica-agent
|
|
```
|
|
|
|
Copy these three files to `/opt/ethica-agent/`:
|
|
|
|
| File | Source |
|
|
|------|--------|
|
|
| `ethica-agent.py` | `EthicaAgents/ethica-agent.py` in this repo |
|
|
| `ethica-agent.yml` | Your config (see Step 3) |
|
|
| `.env` | Your secrets file (see Step 3) |
|
|
|
|
**Via scp from your local machine:**
|
|
|
|
```bash
|
|
scp ethica-agent.py .env ethica-agent.yml root@YOUR_SERVER_IP:/opt/ethica-agent/
|
|
```
|
|
|
|
---
|
|
|
|
## Step 3 — Configure
|
|
|
|
**`.env`** — secrets only, never commit this file:
|
|
|
|
```bash
|
|
cat > /opt/ethica-agent/.env << 'EOF'
|
|
ETHICA_TOKEN=paste-your-company-token-here
|
|
ETHICA_HOME=https://ethica.no
|
|
ETHICA_GROUP=my-server-name
|
|
EOF
|
|
chmod 600 /opt/ethica-agent/.env
|
|
```
|
|
|
|
`ETHICA_GROUP` is the name shown as the server card in the dashboard (e.g. `web-01`, `mail`, `db-prod`). Defaults to the system hostname if omitted.
|
|
|
|
**`ethica-agent.yml`** — what to monitor:
|
|
|
|
```yaml
|
|
interval: 60 # seconds between pushes
|
|
|
|
widgets:
|
|
- type: system_cpu
|
|
name: CPU
|
|
degrade_threshold: 80 # % → degraded status
|
|
offline_threshold: 95 # % → offline status
|
|
|
|
- type: system_memory
|
|
name: Memory
|
|
degrade_threshold: 85
|
|
offline_threshold: 97
|
|
|
|
- type: system_disk
|
|
name: Disk /
|
|
path: /
|
|
degrade_threshold: 80
|
|
offline_threshold: 95
|
|
```
|
|
|
|
See `widgets/` folder for more config packs (nginx, postgres, redis, docker, custom checks).
|
|
|
|
---
|
|
|
|
## Step 4 — Test
|
|
|
|
```bash
|
|
cd /opt/ethica-agent
|
|
set -a && source .env && set +a
|
|
python3 ethica-agent.py --config ethica-agent.yml --once
|
|
```
|
|
|
|
Expected output:
|
|
```
|
|
Ethica Agent 0.1.0 platform=Linux home=https://ethica.no widgets=3 interval=60s
|
|
[online ] CPU → 200
|
|
[online ] Memory → 200
|
|
[online ] Disk / → 200
|
|
```
|
|
|
|
If you see `401 Unauthorized`: the token is wrong or not yet generated (Step 1).
|
|
If you see `NET-ERR` with a connection error: check that `ETHICA_HOME` is reachable from the server.
|
|
|
|
---
|
|
|
|
## Step 5 — Install as systemd service
|
|
|
|
```bash
|
|
cat > /etc/systemd/system/ethica-agent.service << 'EOF'
|
|
[Unit]
|
|
Description=Ethica Agent
|
|
After=network-online.target
|
|
Wants=network-online.target
|
|
|
|
[Service]
|
|
WorkingDirectory=/opt/ethica-agent
|
|
EnvironmentFile=/opt/ethica-agent/.env
|
|
ExecStart=/usr/bin/python3 /opt/ethica-agent/ethica-agent.py --config /opt/ethica-agent/ethica-agent.yml
|
|
Restart=always
|
|
RestartSec=15
|
|
StandardOutput=journal
|
|
StandardError=journal
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
|
|
systemctl daemon-reload
|
|
systemctl enable --now ethica-agent
|
|
systemctl status ethica-agent
|
|
```
|
|
|
|
---
|
|
|
|
## Step 6 — View in dashboard
|
|
|
|
In the Ethica admin panel:
|
|
1. Go to **Companies** → the company → **Monitoring** tab
|
|
2. The server appears as a card under **Agent metrics** with CPU/Memory/Disk bars
|
|
3. To rename a metric or add an IP label: expand it in the **Managed systems** list below and edit
|
|
|
|
---
|
|
|
|
## Maintenance
|
|
|
|
**Check logs:**
|
|
```bash
|
|
journalctl -u ethica-agent -f
|
|
```
|
|
|
|
**Update the agent:**
|
|
```bash
|
|
scp ethica-agent.py root@YOUR_SERVER:/opt/ethica-agent/
|
|
systemctl restart ethica-agent
|
|
```
|
|
|
|
**Rotate the token:**
|
|
```bash
|
|
# 1. Generate new token in admin panel (Company → API → Reset token)
|
|
# 2. Update on the server:
|
|
nano /opt/ethica-agent/.env # change ETHICA_TOKEN=
|
|
systemctl restart ethica-agent
|
|
```
|
|
|
|
**Add more widgets** (e.g. nginx check):
|
|
```bash
|
|
# Append to ethica-agent.yml on the server, then:
|
|
systemctl restart ethica-agent
|
|
```
|
|
|
|
**Stop / uninstall:**
|
|
```bash
|
|
systemctl disable --now ethica-agent
|
|
rm /etc/systemd/system/ethica-agent.service
|
|
rm -rf /opt/ethica-agent
|
|
systemctl daemon-reload
|
|
```
|
|
|
|
---
|
|
|
|
## Docker alternative
|
|
|
|
```bash
|
|
# .env in current dir, ethica-agent.yml mounted as /config/ethica-agent.yml
|
|
docker compose -f docker-compose.example.yml up -d
|
|
```
|
|
|
|
See `docker-compose.example.yml` for the full compose setup.
|