Install via Docker

We recommend installing Hummingbot using Docker if:

You want the simplest, easiest installation method
You don't need to modify the Hummingbot codebase
You want to deploy Hummingbot alongside with Dashboard, Orchestation Module, and other advanced configurations

The instructions below help you install Hummingbot and its companion modules using Docker. Using Docker for Hummingbot deployment offers several benefits, such as simplifying the installation process, enabling easy versioning and scaling, and ensuring a consistent and isolated environment for running the bot.

Prequisites¶

Docker¶

The easiest way to install Docker is to install Docker Desktop, which includes Docker Compose along with Docker Engine and Docker CLI which are Compose prerequisites. Here are links to installers for each major OS:

For command-line Linux distributions, you can install Docker Engine following the steps below:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Once you've executed the aforementioned commands, be sure to exit the terminal and log out, then log back in to ensure the changes are applied.

Docker Compose¶

If you installed Docker Desktop, it already comes with Docker Compose. Alternatively, you can install Docker Compose on a standalone basis:

Linux (Ubuntu / Debian)

sudo apt-get update
sudo apt-get install docker-compose-plugin

Afterwards, verify that Docker Compose is installed correctly by checking the version:

docker compose version

The output should be: Docker Compose version v2.17.2 or similar. Ensure that you are using Docker Compose V2, as V1 is deprecated.

Deploy Examples¶

The deploy-examples Github repository provides various examples of how to deploy Hummingbot using Docker Compose, a tool for defining and running multi-container Docker applications.

Clone the repo to the machine where you want to deploy Hummingbot:

git clone https://github.com/hummingbot/deploy-examples.git

This is where your encrypted keys, scripts, trades, configs, logs, and other files related to your bots will be saved. The repo contains various sub-folders that help you deploy different Hummingbot configurations, such as:

A single Hummingbot instance
A single Hummingbot instance that auto-starts a strategy or script
Linked Hummingbot and Gateway instances
Multiple instances of Hummingbot

Each sub-folder contains two important files:

docker-compose.yml: The sample configuration file for that deployment type
README.md: A detailed README file that guides users through the steps required to deploy Hummingbot using Docker, including how to build and run the containers, how to configure the bot, and how to monitor its performance.

After you have configured it properly, each deployment can be launched with the command:

docker compose up -d

Deployment Types¶

Please click the links below for the deployment instructions for each configuration.

Single Hummingbot Instance ¶

This installs a single Hummingbot instance as a Docker container.

⭐️⭐️⭐️ We recommend that new Hummingbot users follow this route ⭐️⭐️⭐️

Autostart Hummingbot Instance ¶

This installs a single Hummingbot instance as a Docker container and automatically starts running a pre-configured script or strategy.

Hummingbot + Gateway Instances ¶

This installs a Hummingbot instance linked to a Gateway instance.

Multiple Hummingbot Instances + Gateway ¶

This installs two Hummingbot instances, linked to a single Gateway instance.

Hummingbot + Gateway + EMQX Broker ¶

This installs a Hummingbot instance linked to a Gateway instance, along with an EMQX Broker instance.

Experimental deployment

This deployment is still undergoing testing, so we recommend using the standalone deployments for message brokers from the hummingbot/brokers repository.

Bash Scripts¶

This is the older method of installing Hummingbot using Docker. You can access the scripts from the /bash_scripts folder in the Deploy Examples repo.

Afterwards, enable script permissions:

sudo chmod a+x *.sh

Then, run the script you need. For example, you can create a new Hummingbot instance by running:

./hummingbot-create.sh

Building Docker Images¶

To build an image for a specific architecture, use the docker build command with the --platform flag.

To build an image that is compatible with multiple architectures, use the docker buildx command. Additionally, Docker Buildx allows you to easily build and test images for different architectures locally, and then push the multiarch image to a registry, simplifying the deployment process.

docker build¶

Here is how to build a Hummingbot Docker image using docker build:

1. Go to the Hummingbot folder

cd hummingbot

2. Build the image

docker build -t myimage:latest .

3. Before pushing an image, you must first tag it with the appropriate name and version using the docker tag command

docker tag myimage myusername/myimage:[tag]

4. Push the image to DockerHub

docker push myusername/myimage:[tag]

docker buildx¶

Here is how to build a multi-architecture Hummingbot Docker image using docker buildx:

1. Go to the Hummingbot folder

cd hummingbot

2. Check if buildx is installed

docker buildx version

3. Create Builder

docker buildx create --name multiarch --platform linux/arm64,linux/amd64

4. Switch to the new builder instance

docker buildx use multiarch

5. Inspect the builder instance

docker buildx inspect --bootstrap

The output should show both arm64 and amd64 platforms in the Platforms field.

6. Build the image and push to Dockerhub

docker buildx build --platform linux/amd64,linux/arm64 --tag myusername/myimage:[tag] --push .

Useful Docker Commands¶

Use the commands below or use the Docker Desktop application to manage your containers:

Create the Compose project¶

docker compose up -d

Stop the Compose project¶

docker compose down

Update the Compose project for the latest images¶

docker compose up --force-recreate --build -d

Give all users read/write permissions to local files¶

sudo chmod -R a+rw <files/folders>

Attach to the container¶

docker attach <container-name>

Detach from the container and return to command line¶

Press keys Ctrl + P then Ctrl + Q

Update the container to the latest image¶

docker compose up --force-recreate --build -d

List all containers¶

docker ps -a

Stop a container¶

docker stop <container-name>

Remove a container¶

docker rm <container-name>