How to Set Up a Local Swarm Development Environment Using FDP-Play

FDP-Play is a community-maintained CLI tool that spins up a complete local Swarm development stack—including a Bee node cluster and Fair Data Protocol (FDP) services—using Docker, allowing you to build and test decentralized applications without remote infrastructure.

Setting up a local Swarm development environment is essential for rapid prototyping of decentralized storage applications. According to the ethersphere/awesome-swarm repository—specifically line 115 of the README.md—FDP-Play provides a containerized solution that bundles the Bee client and FDP services for offline development.

What Is FDP-Play?

FDP-Play is a Docker-based orchestration tool maintained by the Fair Data Society community. It automates the deployment of a multi-node Bee cluster and the Fair Data Protocol micro-services, eliminating the need to configure remote Bee nodes or external network access during development.

The stack includes:

• Bee nodes: The core Swarm clients providing HTTP APIs for data upload, download, and pinning
• FDP services: Micro-services including FDP-API and FDP-Gateway that implement data interoperability on top of Bee
• Docker Compose: A pre-configured composition managing service networking and persistent local volumes

Prerequisites

Before deploying the stack, ensure Docker is installed on your machine. FDP-Play relies entirely on containerization to guarantee consistent environments across different developer workstations.

Installing and Starting the Local Stack

Clone the FDP-Play Repository

Begin by cloning the official repository to access the Docker Compose configuration.

git clone https://github.com/fairDataSociety/fdp-play.git
cd fdp-play

Review the Docker Compose Configuration

The docker-compose.yml file defines the service topology, including three Bee nodes by default, the FDP-API, FDP-Gateway, and PostgreSQL backing stores. You can examine this file at the repository root to understand port mappings and dependency chains.

Start the Services

Launch the entire stack in detached mode. This command pulls the necessary images (Bee, FDP-API, FDP-Gateway, PostgreSQL) and initializes the cluster.

docker compose up -d

Verify the Deployment

Confirm that all containers are healthy and running before proceeding with development.

docker compose ps

The output should show all services as "Up". Expected ports include:

• Bee HTTP API: 1633
• FDP-API: 8080
• FDP-Gateway: 3000

Interacting with Your Local Swarm Environment

Creating a Personal Data Pod

Use the FDP CLI—shipped with the FDP-Play ecosystem—to create personal data pods. The CLI stores configuration in ~/.fdp, which you should mount into the container for persistence.

docker run --rm \
  -v "$(pwd)/.fdp:/root/.fdp" \
  fairdatasociety/fdp-cli pod create \
  --name my-first-pod

Uploading Files via the Bee HTTP API

Upload data directly to the local Bee node using standard HTTP requests. The API returns a Swarm hash for content addressing.

curl -X POST "http://localhost:1633/files" \
  -F "data=@./my-file.txt" \
  -H "content-type: multipart/form-data"

Retrieving Data Through the FDP Gateway

Access stored content through the FDP Gateway, which resolves Swarm hashes and applies Fair Data Protocol metadata such as access controls.

curl "http://localhost:3000/bzz:/<swarm-hash>"

Key Configuration Files

Understanding these core files helps you customize your local Swarm development environment:

• docker-compose.yml: Defines the complete service stack, networking, and volume mounts. Located at the repository root in fairDataSociety/fdp-play.
• .env.example: Template for environment variables including Bee passwords and PostgreSQL credentials. Copy this to .env to override defaults.
• scripts/init.sh: Optional helper script that pre-creates default pods and configures services on first run.
• README.md (Awesome-Swarm): The canonical reference listing FDP-Play within the Swarm ecosystem at line 115.

Summary

• FDP-Play provides a containerized local Swarm stack combining Bee nodes and FDP services.
• The tool is documented in the ethersphere/awesome-swarm repository and maintained by the Fair Data Society community.
• Default deployment uses Docker Compose with three Bee nodes, exposing ports 1633 (Bee), 8080 (FDP-API), and 3000 (FDP-Gateway).
• You interact with the stack via the FDP CLI for pod management and standard HTTP clients for data upload/download.
• Configuration persists through mounted volumes at ~/.fdp and customizable .env files.

Frequently Asked Questions

What is the difference between FDP-Play and a standalone Bee node?

FDP-Play orchestrates a complete development ecosystem including multiple Bee nodes and the Fair Data Protocol services (FDP-API, Gateway), whereas a standalone Bee node only provides the core Swarm storage client. FDP-Play enables testing of FDP-specific features like personal data pods and interoperable data permissions locally.

Which ports does FDP-Play expose?

By default, FDP-Play exposes three primary ports: 1633 for the Bee HTTP API, 8080 for the FDP-API service, and 3000 for the FDP-Gateway. These allow direct interaction with Swarm storage and the Fair Data Protocol layer.

How do I persist FDP-CLI configuration between sessions?

Mount a local directory to /root/.fdp inside the CLI container. The command docker run --rm -v "$(pwd)/.fdp:/root/.fdp" fairdatasociety/fdp-cli ensures your pod configurations and credentials survive container restarts.

Can I modify the number of Bee nodes in the cluster?

Yes. Edit the docker-compose.yml file in the fairDataSociety/fdp-play repository to scale the Bee node service replicas. The default configuration deploys three nodes, but you can adjust this to match your specific testing requirements for network resilience or performance scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}