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