Documentation - Central Server - Industrial Test Sequencer

Overview

The SeqMaster Central server is an optional component that aggregates data from multiple testers. It provides centralized user management, sequence distribution, cross-site analytics, and integration with external systems (ERP, MES).

Key Principles

• Optional — Testers work perfectly without Central
• Management only — Central never executes tests, it only collects and distributes data
• Push-only sync — Data flows tester → Central (never the other way for results)
• Eventual consistency — Results sync when network is available
• Tester is authoritative — The tester's local data is always the source of truth

Architecture

Tester 1

Tester 2

Tester N

RPi5 + SQLite

→ results

← sequences

← users

Central Server

Docker + PostgreSQL

→ webhooks

ERP/MES

Optional

Deployment

Central runs as a Docker Compose stack with two containers: the app (FastAPI) and a PostgreSQL database.

Requirements

• Linux server (VPS, on-premise, or cloud VM)
• Docker + Docker Compose
• 1 GB RAM minimum, 2 GB recommended
• Port 9090 (or configure behind reverse proxy)

Docker Compose Setup

docker-compose.yml

version: "3.8"

services:
  app:
    build: .
    ports:
      - "9090:8000"
    environment:
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgresql://seqmaster:${DB_PASSWORD}@db:5432/seqmaster
      - SYNC_API_KEY=${SYNC_API_KEY}
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=seqmaster
      - POSTGRES_USER=seqmaster
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Launch

# Create environment file
cat > .env <<EOF
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
DB_PASSWORD=$(python3 -c "import secrets; print(secrets.token_urlsafe(16))")
SYNC_API_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
EOF

# Start the stack
docker compose up -d

# Verify
curl http://localhost:9090/health

Reverse Proxy (Optional)

For production use with HTTPS, put Central behind Caddy or Nginx:

Caddyfile (auto HTTPS)

central.yourcompany.com {
    reverse_proxy localhost:9090
}

Configuration

Central is configured via environment variables. These can be set in a .env file or passed directly to Docker Compose.

Variable	Required	Description
SECRET_KEY	Yes	JWT signing key. Must be a secure random value.
DATABASE_URL	Yes	PostgreSQL connection string.
SYNC_API_KEY	Yes	API key shared with testers for sync authentication.
JWT_ALGORITHM	No	JWT algorithm (default: HS256).
WEBHOOK_URL	No	URL to POST test results for ERP/MES integration.
WEBHOOK_SECRET	No	HMAC secret for signing webhook payloads.
CORS_ORIGINS	No	Comma-separated allowed origins for CORS.

⚠ Central will refuse to start if SECRET_KEY or DATABASE_URL are left at their default/placeholder values.

Sync Protocol

Testers use a push-only sync model. Data flows from testers to Central on a configurable interval. If the network is down, data queues locally and syncs when connectivity returns.

What Gets Synced

• Test results (tester → Central) — Pass/fail outcomes, measurements, timestamps
• Sequences (Central → tester) — Updated test sequences pulled on sync
• Users (Central → tester) — User accounts for centralized access control
• Tester status (tester → Central) — Health, last seen, hardware inventory

Sync Flow

# Every SYNC_INTERVAL seconds, the tester:

1. POST /api/v1/sync/results # Push pending results
2. POST /api/v1/sync/register # Register/heartbeat
3. GET /api/v1/sync/sequences # Pull new sequences
4. GET /api/v1/sync/users # Pull user updates

Authentication

All sync endpoints require the X-API-Key header:

curl -X POST https://central.yourcompany.com/api/v1/sync/results \
  -H "X-API-Key: your-sync-api-key" \
  -H "Content-Type: application/json" \
  -d '{"tester_id": "Station-01", "results": [...]}'

Central API Endpoints

In addition to the sync endpoints, Central provides management APIs:

GET /health

Health check endpoint. Returns server status.

GET /api/v1/testers

List all registered testers with their status, last seen time, and hardware info.

GET /api/v1/results

Query aggregated test results across all testers. Supports filtering by date, tester, sequence, and status.

GET /api/v1/analytics/yield

Yield analytics: pass rate over time, by tester, by sequence.

POST /api/v1/sequences

Upload a test sequence for distribution to testers.

POST /api/v1/users

Create a user account that syncs to all connected testers.

Webhooks

Central can forward test results to external systems (ERP, MES, quality databases) via webhooks. When a tester syncs results, Central sends a signed POST request to your webhook URL.

Webhook Payload

POST to WEBHOOK_URL

{
  "event": "test_result",
  "tester_id": "Station-01",
  "sequence": "PCB Functional Test",
  "version": "1.2.0",
  "status": "PASS",
  "serial_number": "SN-2026-001234",
  "started_at": "2026-02-13T10:30:00Z",
  "duration_seconds": 45.2,
  "steps": [
    {
      "name": "Measure VCC",
      "status": "PASS",
      "value": 5.02,
      "unit": "V",
      "limits": { "min": 4.8, "max": 5.2 }
    }
  ]
}

Signature Verification

Webhook requests include an HMAC-SHA256 signature in the X-Webhook-Signature header:

# Verify in Python:
import hmac, hashlib

signature = request.headers["X-Webhook-Signature"]
expected = hmac.new(
    WEBHOOK_SECRET.encode(),
    request.body,
    hashlib.sha256
).hexdigest()

assert hmac.compare_digest(signature, expected)

Security

HTTPS

Always use HTTPS in production. Use Caddy (auto-TLS) or Nginx with Let's Encrypt certificates.

API Key Rotation

Rotate SYNC_API_KEY periodically. Update Central first, then update each tester and restart.

Database Backups

Schedule regular PostgreSQL backups: docker exec db pg_dump -U seqmaster seqmaster > backup.sql

CORS

Central restricts CORS to configured origins. Set CORS_ORIGINS to your allowed domains.