75 lines
2.9 KiB
Markdown
75 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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`)
|
|
|
|
```bash
|
|
# 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).
|