Real-time monitoring and AI assistance for your reef tank. Polls your controller, stores years of telemetry, visualizes it on a Grafana dashboard, and provides an AI chat assistant (Ask Nemo) that knows your tank's history.
Currently supports Neptune Apex controllers. Community backends for other controllers (GHL Profilux, CoralVue Hydros) are welcome — see Architecture.
v0.15.7 — Community-ready: CI pipeline, test suite, all backlog closed.
About the author: Built by a reef hobbyist, not a professional developer. See
AUTHOR.md.
🍓 On a Raspberry Pi? Follow the Pi Setup Guide instead — it covers 64-bit OS, swap, and SSD setup specific to Raspberry Pi.
| Requirement | How to Get It |
|---|---|
| Docker + Docker Compose | Install Docker |
| Controller IP | Your controller's local IP address (static IP recommended) |
| Fusion account (Apex) | Free at apexfusion.com — username, password, device ID |
| AI API key (optional) | DeepSeek · OpenAI · Groq · xAI — for Nemo AI assistant |
| ~5 minutes | First deploy wall clock |
git clone https://github.com/niveknow/Reef-IQ.git
cd Reef-IQ
cp .env.example .env
nano .env # fill in your credentials — comments explain where to find each one./setup.sh # provisions datasource + imports dashboard
docker compose up -d --build # 6 containers: InfluxDB, Grafana, Collector, Nemo, Cron, Backup| Service | URL | Login |
|---|---|---|
| Grafana Dashboard | http://<host>:3030 |
admin / your GRAFANA_PASSWORD |
| Ask Nemo | Inside dashboard, or http://<host>:8766 |
AI chat |
| InfluxDB | http://<host>:8086 |
admin / your INFLUX_PASSWORD |
| Backend | Status | What It Collects |
|---|---|---|
| Neptune Apex | ✅ Complete | Probes, outlets, power, Fusion water tests, controller status |
Adding a new backend: implement CollectorBackend in backends/<name>/collector.py. See ARCHITECTURE.md.
Nemo can use any OpenAI-compatible LLM:
| Provider | Model (default) | Setup |
|---|---|---|
| DeepSeek | deepseek-chat |
AI_PROVIDER=deepseek |
| OpenAI | gpt-4o |
AI_PROVIDER=openai |
| Groq | llama-3.3-70b-versatile |
AI_PROVIDER=groq |
| xAI | grok-3 |
AI_PROVIDER=xai |
| OpenRouter | openai/gpt-4o |
AI_PROVIDER=openrouter |
| Custom | any | AI_PROVIDER=custom + AI_BASE_URL |
Reef-IQ/
├── reef_core.py ← shared library (config, retry, InfluxDB)
├── reef_config.yaml ← all tunable settings
├── docker-compose.yml ← 6-service Docker stack
├── setup.sh ← one-command bootstrap
├── backends/ ← controller plugin system
│ ├── base.py ← CollectorBackend interface
│ └── apex/ ← Neptune Apex backend
├── scripts/ ← collector, cron, backup utilities
├── nemo/ ← AI assistant (FastAPI)
├── dashboards/ ← Grafana dashboard JSON
├── tests/ ← pytest suite
├── archive/ ← deprecated / one-time scripts
├── .github/workflows/ ← CI pipeline
└── .env.example ← template for your credentials
# View logs
docker compose logs -f collector # live telemetry
docker compose logs -f nemo # AI chat
docker compose logs -f cron # Fusion syncs
# Update
git pull
docker compose up -d --build
# Stop
docker compose down
# Backup (manual)
./scripts/reef_backup.sh| Issue | Fix |
|---|---|
| "Datasource not found" | Run ./setup.sh — it auto-provisions the InfluxDB datasource |
| Collector offline | Check APEX_HOST in .env — must be controller's local IP |
docker compose not found |
Use docker-compose (v1) or install Docker Compose v2 plugin |
| Nemo not responding | Verify AI_API_KEY and AI_PROVIDER in .env |
| Dashboard import fails | Import manually: Grafana → Dashboards → Import → Upload dashboards/modern-reef-dashboard.json |
| Port conflicts | Edit docker-compose.yml — change 8086:8086 or 3030:3000 |
| No water test data | Fusion credentials incomplete — Nemo still works, scraper still works |
If this project helps keep your tank thriving, consider buying me a coffee. All sponsors get a shoutout in the next release notes.
MIT — see LICENSE.
Built with 🪸 for reef keepers everywhere.