Easy Homelab Server Switch

» Server component «

Explore the docs »

Table of Contents

1. Useful shortcuts
   • Project overview
   • Cloudflare
   • Server
   • Microcontroller (ESP32)
   • Client
2. Getting started
3. Components
   • Main
   • Configuration
   • Configuration module
   • MQTT module
   • Network module
   • TLS module
   • Environment
   • Paths
4. Configuration

Useful shortcuts

Module	Repository	README	License
Project overview
Cloudflare
Server
Microcontroller (ESP32)
Client

(back to top)

Getting started

This repository is part of the Easy Homelab Server Switch project. If you are exploring it for the first time, start with the Project Overview README which explains the architecture and interaction between all components.

(back to top)

Components

The server MQTT agent is organized into small modules, each responsible for a specific part of the system.

Main (main.py)

• Orchestrates the application.
• Executes the system shutdown sequence using dbus-send to communicate with the host's power management service.

(back to top)

Configuration (config.py)

• Defines the central dictionary for broker settings, credentials, and MQTT topic.

(back to top)

Configuration module (config_module.py)

• Provides validation to ensure all critical parameters are present before the system attempts to start.

(back to top)

MQTT module (mqtt_module.py)

• Manages the secure TLS connection to the MQTT broker.
• Implements the Last Will and Testament (LWT) feature to automatically broadcast a "DEAD" state on TOPIC_HEARTBEAT if the agent loses connection (expectedly or unexpectedly).
• Subscribes to TOPIC_SYSTEM and triggers local actions based on incoming remote commands.

(back to top)

Network module (net_module.py)

• Performs network validation by checking physical interface link states and system routing tables.
• Verifies actual internet reachability via low-level socket checks to public DNS server.

(back to top)

TLS module (tls_module.py)

• Manages the CA certificate required for secure MQTT communication.
• Ensures secure storage and retrieval of certificate data within the application's data directory.

(back to top)

Environment (constants.py)

• Defines shared constants used across the application.

(back to top)

Paths (paths.py)

• Resolves and creates the application data directory.

(back to top)

Configuration

The system is configured via the config.py file using environment variables.

Category	Variable	Description
MQTT_CONFIG	ip	The IP address of the cloud cluster in MQTT broker.
	port	The secure MQTT port (default: 8883 for TLS)
	user	Username used for authenticating with the broker.
	pass	Password used for authenticating with the broker.
TOPICS	Check here	and here
---	MQTT_CA_CERTIFICATE	ISRG Root X1 certificate for validating the MQTT broker connection.

(back to top)