EthicaAgents/SETUP.md

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

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

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:

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:

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

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

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:

journalctl -u ethica-agent -f

Update the agent:

scp ethica-agent.py root@YOUR_SERVER:/opt/ethica-agent/
systemctl restart ethica-agent

Rotate the token:

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

# Append to ethica-agent.yml on the server, then:
systemctl restart ethica-agent

Stop / uninstall:

systemctl disable --now ethica-agent
rm /etc/systemd/system/ethica-agent.service
rm -rf /opt/ethica-agent
systemctl daemon-reload

---

Platform-specific notes

ZFS servers (high memory usage)

ZFS uses all available RAM as disk cache (ARC) by design. This causes /proc/meminfo's MemAvailable to appear very low even when the system is healthy, triggering false degraded or offline memory alerts.

Fix: raise the memory thresholds in ethica-agent.yml on ZFS hosts:

- type: system_memory
  name: Memory
  degrade_threshold: 97   # ZFS ARC fills all free RAM — not a real shortage
  offline_threshold: 99

Monitor ZFS pool health instead using custom_cmd (see widgets/custom-cmd.yml):

- type: custom_cmd
  name: rpool
  kind: system
  cmd: H=$(zpool list -H -o health rpool 2>/dev/null); C=$(zpool list -H -o cap rpool 2>/dev/null | tr -d %); [ "$H" = "ONLINE" ] || exit 2; [ "$C" -ge 90 ] && exit 2; [ "$C" -ge 75 ] && exit 1; exit 0

- type: custom_cmd
  name: storage pool
  kind: system
  cmd: H=$(zpool list -H -o health data 2>/dev/null); C=$(zpool list -H -o cap data 2>/dev/null | tr -d %); [ "$H" = "ONLINE" ] || exit 2; [ "$C" -ge 90 ] && exit 2; [ "$C" -ge 75 ] && exit 1; exit 0

Replace rpool / data with your actual pool names (zpool list to check).

---

Servers without sudo (user systemd service)

If the SSH user does not have sudo, use a user-level systemd service instead:

mkdir -p ~/.config/systemd/user/
cat > ~/.config/systemd/user/ethica-agent.service << 'EOF'
[Unit]
Description=Ethica Agent
After=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

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now ethica-agent
systemctl --user status ethica-agent

Auto-start on boot (requires root once):

sudo loginctl enable-linger $USER

Without enable-linger, the user service stops when the SSH session closes.

---

Server groups with spaces in the name

When ETHICA_GROUP contains spaces, quote it in .env:

ETHICA_GROUP="Mail Server"   # correct
ETHICA_GROUP=Mail Server     # wrong — bash splits on space

---

Docker alternative

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