MiniDiscovery

MiniDiscovery is a minimal, self-contained service discovery tool inspired by Consul, built with Python (FastAPI, Twisted, SQLite).

It provides basic service registration, health checking, and discovery via both an HTTP API and a DNS interface.

Core Features

• Service Registration/Deregistration: Register services with address, port, tags, and metadata via an HTTP API.
• Health Checking: Automatically performs simple TCP health checks on registered services.
• HTTP API Discovery: Query for services (including filtering by tags and health status).
• DNS Discovery: Query for healthy services using DNS A, SRV, and TXT records (e.g., _web._tcp.laiska.local, api.laiska.local).
• Authentication: API endpoints are protected using HMAC-signed API tokens.
• Persistence: Uses a simple SQLite database (.db file) for storing service and token information.

Components

The script runs three main components as separate processes:

1. FastAPI Server: Handles the HTTP API requests.
2. Twisted DNS Server: Responds to DNS queries for registered services.
3. Health Checker: Periodically checks the health of registered services.

Quick Start

1. Prerequisites

• Python 3.8+
• Dependencies listed in requirements.txt (pip install -r requirements.txt)

2. Running Directly

# First run: Set the initial admin token environment variable
export MINIDISCOVERY_ADMIN_TOKEN="your_very_secret_admin_token_here"

# Run the script (uses default ports and file paths)
python MiniDiscovery.py

• An HMAC key file (minidiscovery.key) will be generated if it doesn't exist.
• A database file (minidiscovery_data.db) will be created.

3. Running with Docker (Recommended)

(Requires the provided Dockerfile and requirements.txt)

# Build the image
docker build -t minidiscovery:latest .

# Create a directory on host for persistent data (key and db)
mkdir ./md_data
# !!! If you have an existing minidiscovery.key, place it in ./md_data !!!

# Run the container
docker run -d --name minidiscovery \
  -p 8500:8500/tcp \
  -p 10053:10053/tcp \
  -p 10053:10053/udp \
  -v ./md_data:/data \
  -e MINIDISCOVERY_ADMIN_TOKEN="your_very_secret_admin_token_here" \
  minidiscovery:latest

• The container expects the database and HMAC key in the /data volume.
• The MINIDISCOVERY_ADMIN_TOKEN is required on the first run to create the initial admin token.

Configuration

• Database Path: --db-path argument or MINIDISCOVERY_DB_PATH environment variable. (Defaults to minidiscovery_data.db, or /data/minidiscovery_data.db in Docker).
• HMAC Key File: --hmac-key-file argument. (Defaults to minidiscovery.key, or /data/minidiscovery.key in Docker).
• Ports: --api-port, --dns-port.
• Initial Admin Token: MINIDISCOVERY_ADMIN_TOKEN environment variable (needed for first run only).