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

---

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

```yaml
- 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`):

```yaml
- 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:

```bash
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):
```bash
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`:

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

---

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