# How to Set Up a Local Swarm Development Environment Using FDP-Play > Easily set up a local Swarm development environment with FDP-Play Use Docker to spin up a Bee node cluster and FDP services for decentralized app development and testing - Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm) - Tags: getting-started - Published: 2026-03-01 --- **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](https://github.com/ethersphere/awesome-swarm/blob/master/README.md#L115)—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. ```bash git clone https://github.com/fairDataSociety/fdp-play.git cd fdp-play ``` ### Review the Docker Compose Configuration The [`docker-compose.yml`](https://github.com/ethersphere/awesome-swarm/blob/main/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. ```bash docker compose up -d ``` ### Verify the Deployment Confirm that all containers are healthy and running before proceeding with development. ```bash 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. ```bash 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. ```bash 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. ```bash curl "http://localhost:3000/bzz:/" ``` ## Key Configuration Files Understanding these core files helps you customize your local Swarm development environment: - **[`docker-compose.yml`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/scripts/init.sh)**: Optional helper script that pre-creates default pods and configures services on first run. - **[`README.md`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) (Awesome-Swarm)**: The canonical reference listing FDP-Play within the Swarm ecosystem at [line 115](https://github.com/ethersphere/awesome-swarm/blob/master/README.md#L115). ## 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`](https://github.com/ethersphere/awesome-swarm/blob/main/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.