Andreas Hilbig
14a0df4c18
This commit comprehensive updates the API to ensure full compatibility across all major Zabbix versions (6.0 LTS, 6.2, 6.4, and 7.0 LTS) and introduces a local development environment for multi-version testing.
Verified Zabbix Versions:
- Zabbix 7.0 (LTS): Full support, including native `history.push` for telemetry.
- Zabbix 6.4: Supported (excluding `history.push`); uses `hostgroup.propagate` and UUID-based matching.
- Zabbix 6.2: Supported (excluding `history.push`); uses `hostgroup.propagate` and `templategroup.*` methods.
- Zabbix 6.0 (LTS): Supported (excluding `history.push`); includes specific fallbacks:
- JSON-RPC: Restored `auth` field in request body for versions lacking Bearer token support.
- Permissions: Implemented name-based fallback for host/template groups (no UUIDs in 6.0).
- Group Expansion: Automatic manual expansion of group rights during import.
- API Methods: Fallback from `templategroup.*` to `hostgroup.*` methods.
Key Technical Changes:
- Local Development: Added `zabbix-local` Docker Compose profile to launch a complete Zabbix stack (Server, Web, Postgres) from scratch with dynamic versioning via `ZABBIX_VERSION`.
- Query Optimization: Refined dynamic field selection to handle implied fields and ensure consistent output regardless of initial Zabbix parameters.
- Documentation:
- New `local_development.md` HOWTO guide.
- Updated `README.md` with detailed version compatibility matrix.
- Expanded `roadmap.md` with achieved milestones.
- Testing:
- Updated entire Jest test suite (23 suites, 96 tests) to be version-aware and robust against naming collisions.
- Enhanced Smoketest and Regression Test executors with better cleanup and error reporting.
88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# 💻 Local Development Environment
|
|
|
|
This guide provides detailed instructions on how to set up a fully isolated local development environment for the Zabbix GraphQL API using Docker Compose.
|
|
|
|
## 🚀 Overview
|
|
The project includes a Docker Compose profile that launches a complete Zabbix stack alongside the GraphQL API and MCP server. This allows you to develop and test features against different Zabbix versions without needing an external Zabbix installation.
|
|
|
|
### Included Services
|
|
- **`zabbix-graphql-api`**: The main GraphQL server.
|
|
- **`apollo-mcp-server`**: The Model Context Protocol server for AI integration.
|
|
- **`postgres-server`**: PostgreSQL 16 database for Zabbix.
|
|
- **`zabbix-server`**: Zabbix Server (PostgreSQL version).
|
|
- **`zabbix-web`**: Zabbix Web interface (Nginx/PostgreSQL).
|
|
|
|
## 🛠️ Step-by-Step Setup
|
|
|
|
### 1. Start the Environment
|
|
Use the `zabbix-local` profile to start all services. You can optionally specify the Zabbix version using the `ZABBIX_VERSION` environment variable.
|
|
|
|
```bash
|
|
# Start the latest 7.0 (default)
|
|
docker compose --profile zabbix-local up -d
|
|
|
|
# Start Zabbix 6.0 (LTS)
|
|
ZABBIX_VERSION=alpine-6.0-latest docker compose --profile zabbix-local up -d
|
|
```
|
|
|
|
### 2. Configure Zabbix
|
|
Once the containers are running, you need to perform a minimal setup in the Zabbix UI:
|
|
|
|
1. Open `http://localhost:8080` in your browser.
|
|
2. Log in with the default credentials:
|
|
- **User**: `Admin`
|
|
- **Password**: `zabbix`
|
|
3. Navigate to **Administration** > **Users** > **API tokens**.
|
|
4. Create a new token for the `Admin` user (or a dedicated service user) and copy it.
|
|
5. **Create Base Host Group**: The API requires a base host group to exist for importing devices.
|
|
- Navigate to **Configuration** > **Host groups** (or **Data collection** > **Host groups** in Zabbix 7.0).
|
|
- Create a host group named `Roadwork` (or the value of `ZABBIX_EDGE_DEVICE_BASE_GROUP` in your `.env`).
|
|
- **Note**: If your base group is nested (e.g., `Roadwork/Devices`), ensure the full path exists. Zabbix does not automatically create parent groups when creating child groups via the API.
|
|
|
|
### 3. Connect the API
|
|
To connect the GraphQL API to your local Zabbix instance, update your `.env` file with the following values (referenced in `samples/zabbix-local.env`):
|
|
|
|
```env
|
|
# Internal Docker network URL
|
|
ZABBIX_BASE_URL=http://zabbix-web:8080/
|
|
|
|
# The token you created in Step 2
|
|
ZABBIX_PRIVILEGE_ESCALATION_TOKEN=your-newly-created-token
|
|
```
|
|
|
|
### 4. Restart the API
|
|
Apply the configuration by restarting the API container:
|
|
|
|
```bash
|
|
docker compose restart zabbix-graphql-api
|
|
```
|
|
|
|
## ✅ Verification
|
|
You can verify the setup by running a simple query against the local API:
|
|
|
|
```bash
|
|
curl -X POST -H "Content-Type: application/json" \
|
|
-d '{"query": "{ apiVersion zabbixVersion }"}' \
|
|
http://localhost:4001/
|
|
```
|
|
|
|
The `zabbixVersion` should match the version you specified in `ZABBIX_VERSION`.
|
|
|
|
## 💡 Advanced Usage
|
|
|
|
### Data Persistence
|
|
Zabbix data is stored in a named Docker volume called `zbx_db_data`. This ensures that your configuration, templates, and hosts are preserved even if you stop or remove the containers.
|
|
|
|
To perform a clean reset of the environment:
|
|
```bash
|
|
docker compose --profile zabbix-local down -v
|
|
```
|
|
|
|
### Testing Multiple Versions
|
|
The local environment is perfect for testing the API's version-specific logic (e.g. `history.push` vs `zabbix_sender`). Simply change the `ZABBIX_VERSION` variable and restart the stack.
|
|
|
|
Supported tags can be found on the [Zabbix Docker Hub](https://hub.docker.com/u/zabbix).
|
|
|
|
---
|
|
**Related Guide**: [Technical Maintenance](./maintenance.md)
|
|
**Related Reference**: [Zabbix Version Compatibility](../../README.md#-zabbix-version-compatibility)
|