How create Remote Connection between Participant – Sequencer and Mediator on Canton Blockchain

by

Postmortem: Docker Networking Failure in Canton Blockchain Setup

Summary

  • User attempted to deploy Canton blockchain components (Participant, Sequencer, Mediator) as separate Docker containers.
  • Remote connections between containers failed despite individual components running.
  • Core issue: Containers couldn’t establish network communication due to misconfigured Docker networking.

Root Cause

  • Missing Docker network bridge: Containers deployed without explicit Docker network assignment, preventing DNS resolution between containers.
  • Misconfigured Canton ports: Component endpoints pointed to localhost in configurations, which resolved to each container’s isolated loopback instead of shared Docker host.
  • Blocked intra-container traffic: Ports exposed at runtime weren’t accessible outside the container’s private network namespace.

Why This Happens in Real Systems

  • DevOps/SRE teams overlook Docker’s default network isolation when composing multi-container systems.
  • Production configurations often differ fundamentally from local setups.
  • Blockchain applications require precise DNS or IP addressing that isn’t abstracted away by Docker defaults.

Real-World Impact

  • Nodes remain partially federated, halting transaction processing.
  • Critical startup failures in decentralized applications dependent on Canton’s participant-sequencer-mediator triad.
  • Increased time-to-production due to debugging opaque network errors in containerized environments.

Example or Code

Incorrect Participant configuration (using localhost): 

canton.participants.participant1.sequencer.connection = "http://localhost:5001"

The correct configuration leverages Docker’s DNS: 

canton.participants.participant1.sequencer.connection = "http://sequencer:5001"

Missing Docker network initialization: 

# WARNING: Containers lack shared network  
docker run -d --name sequencer ...  
docker run -d --name participant ... # No network linkage

Fixed Docker network workflow: 

docker network create canton-net  
docker run -d --network=canton-net --name sequencer ...  
docker run -d --network=canton-net --name participant ...

How Senior Engineers Fix It

  • Explicit Docker networks: Define a bridge network and link all containers with --network=network-name.
  • Use container-names as DNS: Configure endpoints as http://container-name:port instead of localhost.
  • Verify connectivity: Use docker exec -it participant nslookup sequencer to test DNS.
  • Port-binding hygiene: Avoid -p 127.0.0.1:port:port to permit container-to-container traffic without host exposure.
  • Configuration templating: Use environment variables (e.g., SEQUENCER_HOST=sequencer) in Helm/K8s/docker-compose.

Why Juniors Miss It

  • Assume Docker abstracts all networking layers between containers.
  • Test components individually without verifying inter-container communication.
  • Overlook Canton’s requirement for DNS-resolution by interpreting “container” and “localhost” interchangeably.
  • Prioritize functional correctness (logging, startup) over network topology in configurations.