-
Notifications
You must be signed in to change notification settings - Fork 1
Home
Conluz is an energy community management platform designed to facilitate the operation and management of renewable energy communities. The platform handles member management, supply point tracking, real-time energy telemetry collection, and data visualization for energy cooperatives and community energy projects.
What are Energy Communities? Energy communities are groups of individuals, households, businesses, or organizations that collaborate to manage, generate, consume, and potentially distribute energy collectively. These communities promote sustainability, energy efficiency, and local energy production through shared resources and collaborative efforts.
- 📱 Application Documentation
- 📡 Telemetry & IoT Infrastructure
- 🏗️ Infrastructure & Operations
- 👩💻 Developer Resources
All documentation is organized in the root directory by topic area:
📱 Application Documentation:
- Glossary
- How to load a list of users
- How to load a list of supplies
- Scheduled jobs
- Precio (Price)
- Producción (Production)
👩💻 Developer Resources:
- Debug conluz running in Docker with IntelliJ IDEA
🏗️ Infrastructure & Operations:
- Configure Docker without sudo
- Backup and restore InfluxDB database
- Monitor Raspberry Pi with Prometheus/Grafana
📡 Telemetry & IoT Infrastructure:
- MQTT Bastion Setup Guide (main)
- Phase 1: Network Discovery
- Phase 2: Firewall Setup
- Phase 3: SSH Hardening
- Phase 4: Router Port Forwarding
- Phase 5: Monitoring and Logging
- Phase 6: Testing and Verification
- Phase 7: Advanced Security
- Cloudflare DDNS Setup
- Mosquitto MQTT Broker Installation
- Troubleshooting and Maintenance
This section covers the core business functionality of the Conluz platform, including data models, import procedures, and system operations.
Essential terminology and definitions for understanding energy community concepts. This page defines key terms including Energy Community, CUPS (Unique Supply Point Code), Partition Coefficient, Plant, and Supply. Start here to understand the domain language used throughout the platform and documentation.
Step-by-step guide for bulk user creation using CSV file import. Covers CSV format requirements, API endpoint usage with authentication, example curl commands, and response handling. Includes information about validation, error handling, and verification of imported users through the users API endpoint.
How to load a list of supplies
Comprehensive guide for importing supply point data in bulk. Explains the CSV format for supply points, the import API endpoint, authentication requirements, and best practices for data preparation. Essential for onboarding new energy community members with their associated supply points and CUPS codes.
Documentation of automated background jobs and scheduled tasks in the Conluz platform. Describes the timing, purpose, and functionality of each scheduled job including data synchronization tasks, price updates, production calculations, and maintenance operations.
Details about the price synchronization and management functionality. Covers how energy prices are obtained, synchronized, stored, and made available to the system for billing calculations and cost analysis within the energy community.
Documentation of energy production tracking and reporting features. Explains how production data from community-owned generation assets (solar, wind, etc.) is collected, stored, aggregated, and made available for distribution calculations and member allocation.
This section provides comprehensive guides for setting up a secure, Internet-facing MQTT broker for collecting real-time energy telemetry from IoT devices while maintaining network isolation from your local infrastructure.
The comprehensive overview guide for configuring a Raspberry Pi as a secure MQTT bastion host. This guide provides the executive summary, architecture overview, security posture analysis, and navigation to all seven implementation phases. It explains the DMZ-like isolation approach, traffic flow patterns, and security trade-offs. Start here to understand the complete architecture before diving into individual phases.
Follow these guides sequentially to build a secure MQTT bastion host:
Discover and document your network topology before configuration. This phase guides you through identifying network interfaces (eth0/wlan0), determining local subnets, locating your router's IP address, and verifying DNS configuration. Includes techniques for discovering devices on local networks when working headlessly, using tools like arp-scan and nmap.
Core security implementation using iptables to create network isolation. Configure comprehensive firewall rules that block all traffic by default, then selectively allow SSH from local network, MQTT from anywhere (with rate limiting), and Internet access for updates. Critically implements blocking of all outbound connections to RFC 1918 private subnets to prevent lateral movement.
Harden SSH access and implement intrusion prevention. Configure key-based authentication, disable password authentication and root login, and implement fail2ban for automatic blocking of brute-force attempts. Includes custom fail2ban filters for Mosquitto MQTT broker to detect and block authentication attacks and excessive connection attempts.
Phase 4: Router Port Forwarding
Configure your home router to make the MQTT broker accessible from the Internet. Create port forwarding rules for MQTT traffic (port 1883), set up DHCP reservations for static local IP, and configure router firewall settings. Includes guidance for finding router admin interfaces and locating settings across different router models.
Phase 5: Monitoring and Logging
Establish comprehensive logging and monitoring for security visibility. Configure centralized logging for firewall blocks, set up real-time log monitoring, implement log rotation to prevent disk exhaustion, and create disk usage monitoring alerts. Learn to analyze logs for security incidents and troubleshoot connectivity issues.
Phase 6: Testing and Verification
Comprehensive test suite to verify all security measures function correctly. Systematically test firewall rules, verify SSH local-only access, confirm Pi cannot access local network, ensure Internet connectivity works, and validate MQTT access from both Internet and local sources. Includes both positive tests (allowed traffic) and negative tests (blocked traffic).
Advanced security enhancements beyond the basic configuration. Covers TLS/SSL encryption for MQTT traffic (highly recommended), connection rate limiting implementation, monitoring alerts for automated notifications, system update procedures, and evaluation of VPN alternatives like Tailscale or WireGuard for enhanced security models.
Configure dynamic DNS using Cloudflare and ddclient to maintain stable hostname resolution when your ISP assigns dynamic IP addresses. Provides step-by-step instructions for setting up Cloudflare API tokens, configuring ddclient, and automating DDNS updates. Essential for home Internet connections without static IPs.
Mosquitto MQTT Broker - Installation and Troubleshooting Guide
Detailed guide for installing and configuring the Mosquitto MQTT broker on Raspberry Pi. Covers installation procedures, basic configuration, user authentication setup, ACL (Access Control List) configuration, and common troubleshooting scenarios. Prerequisite knowledge for the MQTT Bastion Setup.
Troubleshooting and Maintenance
Comprehensive troubleshooting procedures and ongoing maintenance schedules. Covers common issues including SSH connection refusals, MQTT connection failures, persistent local network access, and package update failures. Includes maintenance checklists for weekly, monthly, quarterly, and annual tasks, plus backup procedures and documentation practices.
This section covers server infrastructure configuration, data storage management, and system observability for operating Conluz in production environments.
Configure Docker to not require sudo in Ubuntu Server
Step-by-step instructions for enabling non-root Docker command execution. Create a docker group, add users to it, and configure socket permissions so Docker commands can run without sudo. Improves developer experience and enables CI/CD automation without elevated privileges.
Backup and restore InfluxDB database
Procedures for backing up and restoring the InfluxDB time-series database used for storing energy telemetry data. Covers backup strategies, automated backup scheduling, backup verification, restoration procedures, and disaster recovery planning. Critical for protecting production energy data and ensuring business continuity.
Monitor a Raspberry Pi 4 with Node Exporter - Prometheus - Grafana
Complete guide for setting up infrastructure monitoring using the Prometheus ecosystem. Install Node Exporter on Raspberry Pi to expose system metrics, configure Prometheus for metric collection and storage, and set up Grafana dashboards for visualization. Enables monitoring of CPU, memory, disk, network, and temperature metrics for IoT edge devices.
This section provides development environment setup and debugging guidance for contributors working on the Conluz platform.
Debug conluz running in a Docker container through IntelliJ IDEA
Comprehensive guide for debugging the Conluz Spring Boot application running in Docker containers using IntelliJ IDEA. Covers docker-compose.yml modifications to expose debug ports, configuring Java debug agent options, setting up Docker Compose run configurations, creating Remote JVM Debug configurations, and establishing the debugging workflow with breakpoints and variable inspection.
To contribute to this wiki:
- Add new documentation files to the root directory
- Use descriptive filenames with hyphens for spaces
- Include clear section headings and navigation links
- Update this Home page when adding new documentation
- Maintain consistency with existing documentation style
If you encounter issues or have questions:
- Check the relevant documentation section above
- For telemetry/MQTT issues, start with Troubleshooting and Maintenance
- Review logs and error messages as indicated in the guides
- Open an issue in the main repository if documentation is unclear or incorrect
For source code, issues, and releases, visit the main Conluz repository (link to be added).
Last Updated: 2026-01-30