Skip to content

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 pull hummingbot/hummingbot

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 pull hummingbot/hummingbot

List all containers

docker ps -a

Stop a container

docker stop <container-name>

Remove a container

docker rm <container-name>