Skip to main content

Use Docker to build and run dapps

What is Docker?

Welcome to the world of Docker, an essential tool for software development. Docker packages software into units known as containers, ensuring consistency, isolation, portability, and scalability.

Docker is particularly useful in dapp development. It helps manage microservices, maintain consistent environments throughout development stages, and simulate a decentralized network during testing.

Understanding Docker begins with understanding Docker images and containers. A Docker image, created from a Dockerfile, is a package that contains everything needed to run the software. A Docker container is a running instance of this image.

Building and Running a Docker Image

You can create a Docker image using the docker build command with a Dockerfile. Once the image is created, you can run a Docker container using the docker run command.

In the context of the example Soroban dapps, understanding how to build Docker images is crucial. The Docker images serve as the basis for our container, which provides the environment for our dapp to run.

Here's an example from our example

To illustrate the process, let's take an example from our example crowdfund dapp. In order to build the Docker image, you utilize a command that is encapsulated within our Makefile:

make build-docker

This command simplifies the Docker build process and ensures it's consistently executed each time. When you run make build-docker, Docker executes the following instructions:

docker build . \
--tag soroban-preview:11 \
--force-rm \

Makefile Overview

docker build .

Instructs Docker to build an image using the Dockerfile in the current directory (denoted by the ".").

--tag soroban-preview:11

Gives a name and tag to our image, in this case, soroban-preview with the tag 9.


Ensures Docker removes any intermediate containers after the build process completes. This keeps our environment clean.


Guarantees the removal of the intermediate container, even if the build fails. By using make build-docker, you're harnessing the power of Docker to create a consistent, reliable environment for our dapp.

Container Deployment

You can streamline the deployment process by using a script to run the Docker container. The following script is a wrapper for the stellar/quickstart Docker image, which provides a quick way to run a Stellar network. You can find an example of the script located in the root directory of the example crowdfund dapp.

set -e

case "$1" in
echo "Using standalone network"
echo "Using Futurenet network"
echo "Usage: $0 standalone|futurenet"
exit 1


# Run the soroban-preview container
# Remember to do:
# make build-docker

echo "Creating docker soroban network"
(docker network inspect soroban-network -f '{{.Id}}' 2>/dev/null) \
|| docker network create soroban-network

echo "Searching for a previous soroban-preview docker container"
containerID=$(docker ps --filter="name=soroban-preview" --all --quiet)
if [[ ${containerID} ]]; then
echo "Start removing soroban-preview container."
docker rm --force soroban-preview
echo "Finished removing soroban-preview container."
echo "No previous soroban-preview container was found"

docker run -dti \
--volume ${currentDir}:/workspace \
--name soroban-preview \
-p 8001:8000 \
--ipc=host \
--network soroban-network \

# Run the stellar quickstart image

docker run --rm -ti \
--name stellar \
--network soroban-network \
-p 8000:8000 \
stellar/quickstart:testing \
--enable-soroban-rpc \
"$@" # Pass through args from the CLI

The script sets up the Docker environment for running the dapp. It allows you to choose between a standalone network or the Futurenet network. The script performs the following steps:

  • Determines the network based on the provided argument (standalone or futurenet).
  • Creates the Docker network named soroban-network if it doesn't exist.
  • Removes any existing soroban-preview Docker container.
  • Runs the soroban-preview container, which provides the Soroban Preview environment for development.
  • Runs the stellar/quickstart Docker image, which sets up the Stellar network using the chosen network type and enables Soroban RPC.