# Troubleshooting & Operation Guide

This guide provides solutions to common issues and a reference for essential operational commands.

## Common Operations (Docker)

These commands assume you are in the project root directory.

### Start/Stop Application

**Start everything (detached mode):**
```bash
docker compose up -d
```

**Stop everything:**
```bash
docker compose down
```

### Updates & Rebuilds

**Pull latest code and rebuild:**
```bash
git pull origin main
docker compose up -d --build
```

**Rebuild only one service (e.g., backend):**
```bash
docker compose up -d --build backend
```

### Logs & Monitoring

**View live logs for all services:**
```bash
docker compose logs -f
```

**View logs for specific service:**
```bash
docker compose logs -f backend
docker compose logs -f frontend
```

### Database Maintenance

**Access database console:**
```bash
docker compose exec db psql -U vulnmanager -d vulnmanager
```

**Run migrations manually:**
```bash
docker compose exec backend alembic upgrade head
```

---

## Troubleshooting Guide

### 1. "Database unreachable" or "Connection refused"
**Symptoms:** Backend crashes on startup, logs show `OperationalError`.

**Solutions:**
*   Ensure the database container is running: `docker compose ps`
*   Check if `POSTGRES_PASSWORD` in `.env` matches the one in the database.
*   **Fix:** If you changed the password in `.env` *after* the first run, you must delete the existing database volume to reset it (WARNING: Data loss):
    ```bash
    docker compose down -v
    docker compose up -d
    ```

### 2. Wazuh Synchronization Failed
**Symptoms:** "Wazuh API Error", "Authentication failed", or assets not appearing.

**Solutions:**
*   **Check Credentials:** Verify API URL, Username, and Password in `Settings` > `Wazuh`.
*   **Self-Signed Certificates:** If Wazuh uses a self-signed cert, ensure `Verify SSL` is unchecked in Settings.
*   **Network:** Check if the backend container can reach the Wazuh manager.
    ```bash
    docker compose exec backend curl -v -k https://<YOUR_WAZUH_IP>:55000
    ```

### 3. "Violations: 3" (Red Card in Dashboard)
**Context:** This was a legacy placeholder card.
**Status:** It has been removed in the latest version. If you still see it, clear your browser cache or rebuild the frontend container.

### 4. Scheduler / Emails Not Sending
**Symptoms:** No emails on SLA breach, or scans not starting.

**Solutions:**
*   **Check Logs:** Look for scheduler errors in backend logs: `docker compose logs -f backend | grep scheduler`
*   **SMTP:** Go to `Settings` -> `SMTP` and use the "Test Connection" button.
*   **Timezone:** Ensure `TIMEZONE` in `.env` is correct (`Europe/Zurich`, etc.) for correct scheduling.

### 5. Deployment Issues (Permission Denied)
**Symptoms:** `EACCES` or permission errors in Docker logs.

**Solutions:**
*   Ensure scripts are executable:
    ```bash
    chmod +x *.sh
    ```
*   Ensure Docker runs with sufficient privileges or as the correct user.

---

## Support

For further assistance, please open an issue on Gitea or contact support:
**Email:** support-vulncheck.sq9vd@passmail.net
