docs: add server setup playbook (SETUP.md)

2026-06-15 20:16:26 +02:00
parent 94e79becd8
commit dee78c3c08
1 changed files with 193 additions and 0 deletions
@@ -0,0 +1,193 @@
+# 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.