PORT_REFERENCE

ThemisDB Port Reference Guide

Stand: 22. Dezember 2025
Version: v1.3.0
Kategorie: 🚀 Deployment

---

📑 Table of Contents

• Overview
• Port Summary Table
• Core Ports

This document provides a comprehensive reference for all ports used by ThemisDB and its optional protocol interfaces.

---

Overview

ThemisDB uses a clean port mapping strategy to separate core functionality from optional protocols. This approach:

• Minimizes attack surface by default (only core ports exposed)
• Provides clear separation of concerns
• Enables flexible deployment configurations
• Follows security best practices (opt-in for additional protocols)

---

Port Summary Table

Port	Protocol/Service	Status	Build Flag Required	Description
8080	HTTP/1.1, GraphQL, HTTP/2	Core	None	REST API, GraphQL endpoint, HTTP/2 upgrade
18765	Wire Protocol, gRPC	Core	None	Binary protocol, gRPC inter-shard communication
4318	OpenTelemetry/OTLP	Core	None	Prometheus metrics, OpenTelemetry collector
1883	MQTT	Optional	-DTHEMIS_ENABLE_MQTT=ON	MQTT broker (plain, unencrypted)
8883	MQTT over TLS	Optional	-DTHEMIS_ENABLE_MQTT=ON	MQTT broker with TLS encryption
8083	MQTT over WebSocket	Optional	-DTHEMIS_ENABLE_MQTT=ON	MQTT broker via WebSocket transport
5432	PostgreSQL Wire Protocol	Optional	-DTHEMIS_ENABLE_POSTGRES_WIRE=ON	PostgreSQL-compatible wire protocol
3000	MCP	Optional	-DTHEMIS_ENABLE_MCP=ON	Model Context Protocol for LLM integration

---

Core Ports (Always Enabled)

Port 8080 - HTTP/REST API

Protocols: HTTP/1.1, HTTP/2 (if enabled), GraphQL
Transport: TCP
TLS: Optional (configure via server.tls in config.json)

Endpoints:

• GET /health - Health check endpoint
• POST /api/query - Query execution
• POST /api/entities - Entity CRUD operations
• POST /graphql - GraphQL endpoint
• GET /metrics - Prometheus metrics (text format)
• GET /api/sse - Server-Sent Events for CDC
• WebSocket upgrade for real-time features (if enabled)

Docker Mapping:

ports:
  - "8080:8080"  # Host:Container

Usage Example:

# Health check
curl http://localhost:8080/health

# Execute query
curl -X POST http://localhost:8080/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n) RETURN n LIMIT 10"}'

---

Port 18765 - Wire Protocol

Protocols: Binary Wire Protocol, gRPC
Transport: TCP
TLS: Optional

Purpose:

• High-performance binary protocol for client SDKs
• gRPC inter-shard communication (Enterprise Edition)
• Optimized for low-latency operations

Docker Mapping:

ports:
  - "18765:18765"

Usage Example:

# Python client
from themisdb import Client

client = Client(host="localhost", port=18765)
result = client.query("MATCH (n) RETURN n LIMIT 10")

---

Port 4318 - OpenTelemetry/Metrics

Protocols: OpenTelemetry Protocol (OTLP), HTTP
Transport: TCP
Format: JSON, Protobuf

Purpose:

• Prometheus metrics scraping
• OpenTelemetry trace/metrics collection
• Integration with observability stacks (Grafana, Datadog, etc.)

Docker Mapping:

ports:
  - "4318:4318"

Prometheus Configuration:

scrape_configs:
  - job_name: 'themisdb'
    static_configs:
      - targets: ['localhost:4318']

---

Optional Protocol Ports

Port 1883 - MQTT (Plain)

Protocol: MQTT 3.1.1, MQTT 5.0
Transport: TCP (plain, unencrypted)
Build Flag: -DTHEMIS_ENABLE_MQTT=ON
Security: ⚠️ Not recommended for production (use 8883 with TLS)

Purpose:

• IoT device connectivity
• Pub/Sub messaging
• Sensor data ingestion

Docker Mapping:

ports:
  - "1883:1883"  # Only if MQTT enabled

Configuration (config.json):

{
  "enable_mqtt": true,
  "mqtt_port": 1883,
  "mqtt_max_clients": 10000,
  "mqtt_qos_support": [0, 1, 2]
}

Client Example (Python):

import paho.mqtt.client as mqtt

client = mqtt.Client("sensor_001")
client.connect("localhost", 1883, 60)
client.publish("sensors/temperature/room1", '{"value": 22.5}', qos=1)

See Also: OPTIONAL_PROTOCOLS.md

---

Port 8883 - MQTT over TLS

Protocol: MQTT 3.1.1, MQTT 5.0 with TLS
Transport: TCP with TLS 1.3
Build Flag: -DTHEMIS_ENABLE_MQTT=ON
Security: ✅ Recommended for production

Purpose:

• Secure IoT device connectivity
• Encrypted pub/sub messaging
• Certificate-based authentication

Docker Mapping:

ports:
  - "8883:8883"  # Only if MQTT enabled

Configuration (config.json):

{
  "enable_mqtt": true,
  "mqtt_tls_port": 8883,
  "mqtt_ssl_enabled": true,
  "mqtt_cert_file": "/etc/themis/certs/server.crt",
  "mqtt_key_file": "/etc/themis/certs/server.key",
  "mqtt_ca_file": "/etc/themis/certs/ca.crt"
}

Client Example (Python):

import paho.mqtt.client as mqtt
import ssl

client = mqtt.Client("sensor_001")
client.tls_set(
    ca_certs="/path/to/ca.crt",
    certfile="/path/to/client.crt",
    keyfile="/path/to/client.key",
    tls_version=ssl.PROTOCOL_TLSv1_2
)
client.connect("localhost", 8883, 60)

---

Port 8083 - MQTT over WebSocket

Protocol: MQTT over WebSocket
Transport: HTTP WebSocket upgrade
Build Flag: -DTHEMIS_ENABLE_MQTT=ON

Purpose:

• Browser-based MQTT clients
• Web applications requiring MQTT
• Firewall-friendly MQTT connectivity

Docker Mapping:

ports:
  - "8083:8083"  # Only if MQTT enabled

Configuration (config.json):

{
  "enable_mqtt": true,
  "mqtt_enable_websockets": true,
  "mqtt_websocket_port": 8083
}

Client Example (JavaScript):

const mqtt = require('mqtt');

const client = mqtt.connect('ws://localhost:8083', {
  clientId: 'webapp_' + Math.random().toString(16).substr(2, 8)
});

client.on('connect', () => {
  client.subscribe('sensors/#');
  client.publish('sensors/temperature/room1', '{"value": 22.5}');
});

---

Port 5432 - PostgreSQL Wire Protocol

Protocol: PostgreSQL Wire Protocol v3.0
Transport: TCP
Build Flag: -DTHEMIS_ENABLE_POSTGRES_WIRE=ON

Purpose:

• PostgreSQL tool compatibility (psql, pgAdmin, DBeaver)
• SQL query interface (translated to Cypher internally)
• BI tool integration (Tableau, Power BI)

Docker Mapping:

ports:
  - "5432:5432"  # Only if PostgreSQL Wire Protocol enabled

Configuration (config.json):

{
  "enable_postgres_wire": true,
  "postgres_port": 5432,
  "postgres_max_connections": 100,
  "postgres_ssl_enabled": true,
  "postgres_auth_method": "md5",
  "postgres_default_database": "themis",
  "postgres_server_version": "14.0"
}

Client Example (psql):

# Connect using psql
psql -h localhost -p 5432 -U themis_user -d themis

# Execute SQL queries (translated to Cypher)
SELECT * FROM users WHERE age > 25;

Client Example (Python psycopg2):

import psycopg2

conn = psycopg2.connect(
    host="localhost",
    port=5432,
    database="themis",
    user="themis_user",
    password="password"
)

cursor = conn.cursor()
cursor.execute("SELECT * FROM users WHERE age > %s", (25,))
rows = cursor.fetchall()

See Also: OPTIONAL_PROTOCOLS.md

---

Port 3000 - MCP (Model Context Protocol)

Protocol: MCP (JSON-RPC)
Transports: stdio, SSE (Server-Sent Events), WebSocket
Build Flag: -DTHEMIS_ENABLE_MCP=ON

Purpose:

• LLM integration (Claude, GPT, local models)
• AI-powered database queries
• Context sharing with language models
• Tool calling for database operations

Docker Mapping:

ports:
  - "3000:3000"  # Only if MCP enabled

Configuration (config.json):

{
  "enable_mcp": true,
  "mcp_port": 3000,
  "mcp_enable_stdio": true,
  "mcp_enable_sse": true,
  "mcp_enable_websocket": true,
  "mcp_server_name": "ThemisDB",
  "mcp_server_version": "1.3.0"
}

MCP Transports:

1. stdio (Claude Desktop):

// Claude Desktop config
{
  "mcpServers": {
    "themisdb": {
      "command": "docker",
      "args": ["exec", "-i", "themisdb-server", "/usr/local/bin/themis_mcp"]
    }
  }
}

2. SSE (HTTP clients):

# Connect via SSE
curl -N http://localhost:3000/mcp/sse

3. WebSocket (bidirectional):

const ws = new WebSocket('ws://localhost:3000/mcp/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    method: "tools/list",
    id: 1
  }));
};

Available MCP Tools:

• query - Execute Cypher/SQL queries
• put_entity - Create/update entities
• get_entity - Retrieve entities by ID
• delete_entity - Delete entities
• create_index - Create database indexes
• get_schema - Retrieve database schema
• get_stats - Get database statistics

See Also:

• MCP_PROTOCOL_SUPPORT.md
• MCP_MINIMAL_INTEGRATION.md

---

Docker Deployment Examples

Minimal Deployment (Core Ports Only)

version: "3.8"
services:
  themisdb:
    image: themisdb:1.3.0
    container_name: themisdb-server
    ports:
      - "8080:8080"     # HTTP API
      - "18765:18765"   # Wire Protocol
      - "4318:4318"     # Metrics
    volumes:
      - themis_data:/data
    restart: unless-stopped

volumes:
  themis_data:

Start:

docker compose up -d
curl http://localhost:8080/health

---

Full Deployment (All Optional Protocols)

Prerequisites:

• Build ThemisDB with all protocol flags enabled
• Configure certificates for TLS protocols

version: "3.8"
services:
  themisdb:
    image: themisdb:1.3.0-full  # Custom build with all protocols
    container_name: themisdb-full
    ports:
      # Core ports
      - "8080:8080"     # HTTP/REST API
      - "18765:18765"   # Wire Protocol
      - "4318:4318"     # Metrics
      
      # Optional protocol ports
      - "1883:1883"     # MQTT plain
      - "8883:8883"     # MQTT TLS
      - "8083:8083"     # MQTT WebSocket
      - "5432:5432"     # PostgreSQL Wire
      - "3000:3000"     # MCP
    volumes:
      - themis_data:/data
      - ./config:/etc/themis:ro
      - ./certs:/etc/themis/certs:ro
    environment:
      THEMIS_CONFIG_PATH: "/etc/themis/config.json"
    restart: unless-stopped

volumes:
  themis_data:

Build Command:

docker build \
  --build-arg ENABLE_MQTT=ON \
  --build-arg ENABLE_POSTGRES_WIRE=ON \
  --build-arg ENABLE_MCP=ON \
  -t themisdb:1.3.0-full .

---

Railway/Cloud Deployment

For Railway, Render, or other cloud platforms with dynamic port assignment:

version: "3.8"
services:
  themisdb:
    image: themisdb:1.3.0
    ports:
      - "${PORT:-8080}:8080"  # Railway assigns PORT dynamically
    environment:
      THEMIS_HTTP_PORT: "${PORT:-8080}"
      THEMIS_WIRE_PORT: "18765"

See Also: examples/railway/docker-compose.railway.yml

---

Port Conflict Resolution

Common Conflicts

Port	Common Conflict	Resolution
8080	Jenkins, Tomcat, other web apps	Map to 8081: "8081:8080"
5432	PostgreSQL	Map to 5433: "5433:5432"
1883	Mosquitto, other MQTT brokers	Map to 1884: "1884:1883"
3000	Node.js dev servers	Map to 3001: "3001:3000"

Example: Resolving Port 8080 Conflict

services:
  themisdb:
    ports:
      - "8081:8080"  # Map host 8081 to container 8080
      - "18765:18765"

Access:

curl http://localhost:8081/health  # Note: 8081 instead of 8080

---

Kubernetes Port Configuration

apiVersion: v1
kind: Service
metadata:
  name: themisdb
spec:
  type: LoadBalancer
  ports:
    - name: http
      port: 8080
      targetPort: 8080
    - name: wire
      port: 18765
      targetPort: 18765
    - name: metrics
      port: 4318
      targetPort: 4318
    # Add optional ports as needed
  selector:
    app: themisdb

---

Security Best Practices

1. Minimize Exposed Ports

Default (Secure):

ports:
  - "8080:8080"   # Only HTTP API
  - "18765:18765" # Only Wire Protocol

Avoid (Unless Needed):

ports:
  - "1883:1883"   # MQTT plain - unencrypted!

2. Use TLS for All Protocols

MQTT:

• Prefer port 8883 (MQTT TLS) over 1883 (plain)
• Configure client certificates

PostgreSQL Wire:

• Enable SSL in config: "postgres_ssl_enabled": true
• Use certificate-based authentication

MCP:

• Use HTTPS/WSS transports in production
• Configure authentication tokens

3. Network Isolation

Docker Network:

networks:
  themisdb_internal:
    driver: bridge
    internal: true  # No external access

services:
  themisdb:
    networks:
      - themisdb_internal
    ports:
      - "8080:8080"  # Only HTTP exposed externally

4. Firewall Rules

Allow only necessary ports:

# UFW (Ubuntu)
ufw allow 8080/tcp    # HTTP API
ufw allow 18765/tcp   # Wire Protocol
ufw deny 1883/tcp     # Block unencrypted MQTT

# iptables
iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
iptables -A INPUT -p tcp --dport 18765 -j ACCEPT
iptables -A INPUT -p tcp --dport 1883 -j DROP

---

Monitoring and Health Checks

Port Availability Checks

# Check if ports are listening
netstat -tuln | grep -E '8080|18765|4318'

# Check HTTP endpoint
curl -f http://localhost:8080/health || echo "HTTP port not responding"

# Check Wire Protocol (telnet)
telnet localhost 18765

Docker Health Check

healthcheck:
  test: ["CMD-SHELL", "curl -fsS http://localhost:8080/health || exit 1"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 10s

Prometheus Metrics

Port Status Metrics:

themis_http_port_open{port="8080"} 1
themis_wire_port_open{port="18765"} 1
themis_mqtt_port_open{port="1883"} 1
themis_postgres_port_open{port="5432"} 1
themis_mcp_port_open{port="3000"} 1

Query:

# Check all ports are open
sum(themis_http_port_open + themis_wire_port_open) == 2

---

Troubleshooting

Port Already in Use

Error:

Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use

Solution 1 - Find and stop conflicting process:

# Find process using port 8080
lsof -i :8080
# or
netstat -tuln | grep 8080

# Kill the process
kill -9 <PID>

Solution 2 - Use different host port:

ports:
  - "8081:8080"  # Map host 8081 to container 8080

Port Not Accessible from Host

Check container logs:

docker logs themisdb-server

Check port binding:

docker port themisdb-server

Check firewall:

# Linux
sudo ufw status
sudo iptables -L

# macOS
sudo pfctl -s rules

Protocol Not Available

Error:

Connection refused on port 5432

Cause: PostgreSQL Wire Protocol not enabled at build time

Solution:

1. Rebuild with protocol flag:

   cmake -B build -S . -DTHEMIS_ENABLE_POSTGRES_WIRE=ON
   docker build --build-arg ENABLE_POSTGRES_WIRE=ON -t themisdb:custom .

2. Update docker-compose.yml:

   services:
     themisdb:
       image: themisdb:custom
       ports:
         - "5432:5432"

---

References

• OPTIONAL_PROTOCOLS.md - Detailed protocol documentation
• MCP_PROTOCOL_SUPPORT.md - MCP integration guide
• DOCKER_DEPLOYMENT.md - Docker deployment guide
• docker-compose.yml - Reference docker-compose configuration
• Dockerfile - Main Dockerfile with port definitions

---

Version History

Version	Date	Changes
1.3.0	2024-12-21	Initial port reference documentation

---

Questions or Issues?
Open an issue on GitHub or refer to CONTRIBUTING.md