Container Deployment (Podman/Docker)
Relevant source files
The following files were used as context for generating this wiki page:The Overlord Network Kill Switch application is designed to be deployed as a container using Podman or Docker. This approach simplifies setup by packaging the FastAPI web server, its dependencies, and the necessary application code into a single, portable image. The container exposes an API to control Pi-hole DNS filtering and Ubiquiti firewall rules, which is then typically integrated with systems like Homebridge and Node-RED.
The container is built on Python 3.12 and uses Gunicorn to serve the FastAPI application. It is configured via environment variables and an optional mounted configuration file (config.ini) for more advanced setups.
Sources: README.md:2-11, AGENTS.md:6-12, pyproject.toml:5-6
Quickstart
The application can be run using a single podman run command. The container image is hosted on GitHub Container Registry (ghcr.io). An environment file (envfile) is required to provide necessary credentials and connection details for the services it manages.
Sources: README.md:32-35
Execution Command
The following command starts the container in detached mode, maps the required port, and loads configuration from an environment file.
# Add if needed -v ./etc/config.ini:/opt/webserver/etc/config.ini
podman run -d --replace --name=overlord-dns -p 19000:19000 --env-file=./etc/envfile ghcr.io/nickjlange/overlord-network-kill-switch:latest
-d: Runs the container in the background.--replace: Replaces an existing container with the same name.--name=overlord-dns: Assigns a name to the container.-p 19000:19000: Maps port 19000 on the host to port 19000 inside the container.--env-file=./etc/envfile: Specifies the file containing environment variables for configuration.-v ./etc/config.ini:/opt/webserver/etc/config.ini: (Optional) Mounts a localconfig.inifile into the container for detailed configuration.
Sources: README.md:39-42, cgi-bin/gunicorn_config.py:2
Configuration
The container is configured primarily through environment variables, which can be supplied in a file specified by the --env-file flag.
Sources: README.md:32-35, AGENTS.md:52-60
Environment Variables
These variables are essential for the container to connect to Pi-hole, Ubiquiti, and MQTT services.
| Variable | Description | Example |
|---|---|---|
DNS_SERVERS | Comma-separated list of DNS server IP addresses. | 192.168.1.53,192.168.1.54 |
REMOTE_PI_PASSWORD | The admin password for the Pi-hole instances. | YourPiHolePassword |
REMOTE_PI_LIST | A space-separated list of Pi-hole IP addresses. | "192.168.1.53 192.168.1.54" |
MQTT_BROKER | The IP address of the MQTT broker. | 192.168.1.100 |
MQTT_PORT | The port for the MQTT broker. | 1883 |
REMOTE_UBIQUITI_DEVICE | The IP address or hostname of the UniFi controller. | 192.168.1.1 |
REMOTE_UBIQUITI_API_KEY | The API key for the UniFi controller. | YourUniFiAPIKey |
Sources: README.md:33-38, AGENTS.md:53-59, cgi-bin/controller.py:100-106
config.ini File
For more granular control, a config.ini file can be mounted into the container at /opt/webserver/etc/config.ini. This file allows for defining specific domain block groups, Ubiquiti target MAC addresses, and firewall rule names. The application reads this file on startup to initialize its control modules.
Sources: README.md:32-35, cgi-bin/controller.py:65-144, AGENTS.md:62-69
Internal Architecture
The container runs a Gunicorn web server which manages worker processes for the FastAPI application defined in controller.py.
This diagram illustrates the flow from container startup to a running application.
Application Stack
The core of the container is a Python-based web application.
| Component | Implementation | Purpose |
|---|---|---|
| Web Server | Gunicorn | A production-grade WSGI HTTP server to run the Python application. |
| Web Framework | FastAPI | A modern, high-performance web framework for building APIs. |
| Application Entrypoint | controller.py | The main FastAPI application file. It initializes configuration, sets up lifespan events (startup/shutdown), and includes API routers. |
| API Routers | pihole_router.py, ubiquity.py | These files define the API endpoints for controlling Pi-hole and Ubiquiti devices, respectively. |
Sources: AGENTS.md:10-11, etc/webserver_requirements.txt:11,12, cgi-bin/controller.py:15-18,171-177, cgi-bin/gunicorn_config.py
Key Dependencies
The application relies on several key Python libraries, which are installed inside the container.
| Package | Version | Purpose |
|---|---|---|
fastapi | >=0.115.12 | Core web framework for the API. |
gunicorn | >=23.0.0 | WSGI server to run the FastAPI app. |
pihole6api | 0.2.0 | Client library for interacting with the Pi-hole v6 API. |
requests | 2.32.4 | Used for making HTTP requests to the Ubiquiti controller API. |
aiomqtt | 2.4.0 | Asynchronous client for publishing status updates to an MQTT broker. |
Sources: etc/webserver_requirements.txt:3,11,12,25,32, AGENTS.md:72-77
Lifespan Management
The application uses FastAPI's lifespan context manager to handle startup and shutdown events within the container.
This sequence diagram shows the application's startup and shutdown procedures.
Sources: cgi-bin/controller.py:158-186
On startup, the application:
- Initializes configuration from
config.iniand environment variables. - Initializes the Pi-hole and Ubiquiti control modules.
- Publishes a "true" message to the configured MQTT Last Will and Testament (LWT) topics to indicate the service is online.
On shutdown, it gracefully:
- Closes sessions to the Pi-hole and Ubiquiti controllers.
- Publishes a "false" message to the MQTT LWT topics.
Sources: cgi-bin/controller.py:158-186