System overview


Using the local:docker runner of Testground enables you to test distributed/p2p systems on your local machine with precisely the same build artifacts as the cluster:k8s runner. The use of Docker images as a build target ensures plans are built the same way with the same build environment even when built on a different machine or a different OS.

The overall performance of the local:docker runner depends highly on the machine running the tests, though we are frequently able to run tests with 100+ instances without issue using commonly-available laptops or desktop computers.


Aside from the sidecar, which is built separately, any auxiliary Docker images are downloaded if needed. This is what you need to get started:

  • A laptop or desktop with reasonable hardware specs. To be able run simulations of a reasonable size, we recommend at least the following:

    • 8GB memory

    • 50GB available storage

  • The following software setup is required:

    • Docker daemon

    • a non-root account with write access to the Docker socket.

    • Sidecar container installation. See installation instructions in Getting Started‚Äč

Testground-supplied containers

When Testground runs its first plan, several additional containers will be downloaded and started. Here is an overview of everything Testground adds to your system

  • Docker networks:

    • testground-build

      • This network is used only during the build phase.

      • Test plan containers are not attached to this network.

    • testground-control

      • This network is used by test plan containers to communicate with the sync service and the host.

      • Though this is a public-facing network, plan containers cannot access the internet through this network because routes are removed.

    • testground-data

      • Plan containers communicate with each other over this network.

      • This is the network used for testing.

      • The sidecar modifies the link quality and performance to simulate real-world conditions.

  • Docker containers:

    • goproxy

      • This container is attached to the build network.

      • It speeds up Go builds.

      • It is optional.

    • redis

      • This is the backend database of the Testground sync service.

    • grafana

      • Visualisation software that Testground uses for its dashboards.

    • influxdb

      • Time-series database that Testground uses for various diagnostics and events.