mbrindam/direct-test-peer repository overview

⁠Docker Hub: direct-test-peer

Image: docker.io/mbrindam/direct-test-peer

Multiplatform image for §170.315(h)(1) Direct Protocol round-trip testing. Supports linux/amd64 and linux/arm64.

⁠Quick start

⁠Single test peer (against ClaudeEHR or external gateway)

docker run -d \
  --name direct-test-peer \
  -p 8890:3003 \
  -p 2526:2525 \
  -e PEER_GATEWAY_URL=http://direct-gateway:3002 \
  -v direct_test_peer_certs:/certs \
  mbrindam/direct-test-peer:latest

Dashboard: http://localhost:8890⁠

⁠Two peers (bidirectional cross-org testing)

docker network create direct-peers

# Peer A
docker run -d \
  --name direct-test-peer-a \
  --network direct-peers \
  -p 8890:3003 \
  -p 2526:2525 \
  -e DIRECT_DOMAIN=direct.test-peer-a.local \
  -e PEER_GATEWAY_URL=http://direct-test-peer-b:3003 \
  -e PEER_SMTP_HOST=direct-test-peer-b \
  -v direct_test_peer_a_certs:/certs \
  mbrindam/direct-test-peer:latest

# Peer B
docker run -d \
  --name direct-test-peer-b \
  --network direct-peers \
  -p 8891:3003 \
  -p 2527:2525 \
  -e DIRECT_DOMAIN=direct.test-peer-b.local \
  -e PEER_GATEWAY_URL=http://direct-test-peer-a:3003 \
  -e PEER_SMTP_HOST=direct-test-peer-a \
  -v direct_test_peer_b_certs:/certs \
  mbrindam/direct-test-peer:latest

Dashboards:

• Peer A: http://localhost:8890⁠
• Peer B: http://localhost:8891⁠

⁠Using docker-compose (recommended)

See the project repository for docker-compose.yml configurations:

⁠Single peer

git clone https://github.com/mbrindam/direct-test-peer.git
cd direct-test-peer
docker compose up -d

⁠Two peers

docker compose -f docker-compose.yml -f docker-compose.two-peer.yml up -d

⁠Environment variables

Note: If PEER_GATEWAY_URL is empty, the peer will skip trust exchange on startup but remain operational. You can manually exchange trust via REST API.

⁠REST API endpoints

All endpoints available at http://localhost:3003 (or your container's REST port).

⁠Send messages

• POST /send — Send S/MIME Direct message with custom CDA XML
• POST /send-sample — Send a bundled sample (ccd-full, ccd-minimal, discharge-summary)

⁠Inbox & outbox

• GET /api/inbox — Received messages (JSON, newest first)
• GET /api/outbox — Sent messages (JSON, newest first)
• GET /api/stats — Message counts and trust status

⁠PKI management

• GET /certs/ca — Own CA certificate (PEM)
• GET /certs/<address> — Address certificate (PEM)
• POST /certs/trust — Import trusted CA cert and name

⁠Health

• GET /health — Service readiness check

See repository README for detailed API examples.

⁠Ports

⁠Volumes

Mount /certs to persist PKI data across container restarts:

-v my-certs-volume:/certs

This volume holds:

• ca.key, ca.crt — Organization CA keypair
• domain.key, domain.crt — Domain certificate
• addr/ — Per-address certificates
• trusted/ — Imported peer CA certificates
• trust-bundle.pem — Combined trust store

To reset PKI and start fresh:

docker volume rm my-certs-volume
docker run ... -v my-certs-volume:/certs mbrindam/direct-test-peer:latest

⁠Supported architectures

• linux/amd64 (x86-64)
• linux/arm64 (ARM 64-bit, Apple Silicon, Raspberry Pi 4+)

Automatically selected based on your Docker host. Explicit pull:

docker pull mbrindam/direct-test-peer:latest --platform linux/arm64

⁠Networking

⁠Single peer with docker-compose network

If your peer gateway (e.g., ClaudeEHR) runs in the same compose project:

services:
  direct-test-peer:
    image: mbrindam/direct-test-peer:latest
    environment:
      PEER_GATEWAY_URL: http://direct-gateway:3002
    networks:
      - default  # Same network as direct-gateway

⁠Two peers (isolated network)

docker network create direct-peers
docker run ... --network direct-peers ... mbrindam/direct-test-peer:latest

⁠Use cases

⁠Building locally

Clone the repository and build:

git clone https://github.com/mbrindam/direct-test-peer.git
cd direct-test-peer

# Single-platform build
docker build -t my-direct-test-peer:latest .

# Multiplatform build (requires buildx)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t my-direct-test-peer:latest \
  .

⁠Troubleshooting

⁠Trust exchange fails on startup

Check logs:

docker logs direct-test-peer

Common issues:

• Peer not reachable: Verify PEER_GATEWAY_URL is correct and peer is running
• Network isolation: Ensure containers share a Docker network or are on the host network
• Retry exhausted: Peer tries to exchange trust 15 times with exponential backoff; wait 2-3 minutes

⁠Cannot send/receive messages

1. Verify trust exchange succeeded: curl http://localhost:8890/api/stats
2. Check dashboard at http://localhost:8890/⁠
3. If trust is missing, manually exchange via REST:

   # Get peer's CA
   curl http://peer-gateway:3002/certs/ca | \
     curl -X POST http://localhost:8890/certs/trust \
       -H 'Content-Type: application/json' \
       -d '{"name": "peer-ca", "cert": "@-"}'
   

   Copy

⁠SMTP delivery fails

Verify SMTP configuration:

• PEER_SMTP_HOST must be reachable from container
• PEER_SMTP_PORT must match peer's SMTP listener (usually 2525)
• For cross-container delivery, ensure same Docker network

⁠GitHub repository

Full source, documentation, and docker-compose configurations: https://github.com/mbrindam/direct-test-peer⁠

⁠License

MIT