Skip to content

Installation

New vs Legacy

In the v2.3 release, Gateway started to undergo a large refactor, as approved in proposal NCP-22. During this process, only certain reference connectors will be upgraded to the new architecture, while bounties funded by available Connector Pots will fund developer bounties to migrate other connectors.

To enable users to use legacy connectors during the refactor, the Hummingbot fix/gateway-2.2 branch is compatible with Gateway v2.2.0, the last version that contains all the legacy connectors. This branch will be kept updated with the Hummingbot development while the refactor is in progress.

Hummingbot fix/gateway-2.2 branch:

Gateway v2.2.0 branch:

The instructions below use these versions.

Install with Docker

For most users, this is the recommended install method for Hummingbot and Gateway

Navigate to the Hummingbot root folder in your terminal or if you haven't cloned the Hummingbot repo yet run the command below

git clone -b fix/gateway-2.2 https://github.com/hummingbot/hummingbot.git
cd hummingbot

Next, modify the docker-compose.yml file in the hummingbot root folder using a text editor or IDE like VSCode.

Make the following edits:

  • Update the Docker image tags for hummingbot and gateway.

  • Uncomment the Gateway section.

  hummingbot:
    image: hummingbot/hummingbot:gateway-2.2

    gateway:
    container_name: "gateway"
    image: hummingbot/gateway:version-2.2.0    
    ports:
      - "15888:15888"
      - "8080:8080"
    volumes:
      - "./gateway_files/conf:/usr/src/app/conf"
      - "./gateway_files/logs:/usr/src/app/logs"
      - "./hummingbot_files/certs:/home/gateway/certs"
    environment:
      - GATEWAY_PASSPHRASE=a

Start Hummingbot & Gateway

docker compose up -d
docker attach hummingbot

Note

It's normal for the Gateway container to stop immediately after the initial launch. You will need to generate certificates and set a passphrase in the following steps to complete the setup.

Generate Gateway certificates

Within the Hummingbot terminal, set your password. Then, issue the command below to generate the Gateway certificates. You will be prompted for a passphrase for the certificate's private key. Note that this passphrase can be, but does not have to be, identical to your Hummingbot password.

gateway generate-certs

Generate Certificates

Exit Hummingbot:

exit

Then stop the Docker containers:

docker compose down

Add passphrase to YAML file

Edit docker-compose.yml again to ensure the passphrase matches your previously set GATEWAY_PASSPHRASE:

environment:
  - GATEWAY_PASSPHRASE=a # Replace "a" with the passphrase that you set with the `gateway generate-certs` command

Save your changes.

Restart Hummingbot and Gateway

Restart Docker containers:

docker compose up -d
docker attach hummingbot

You should now see GATEWAY:ONLINE at the top-right corner.

Gateway Status

Check Gateway logs

View Gateway logs:

docker logs gateway

Once Gateway is running, proceed to Testing Gateway to confirm functionality

Install from Source

You can also install Gateway on a standalone basis and then link it to Hummingbot manually. These instructions assume that you have already installed Hummingbot on the machine where you are installing Gateway, either from source or via Docker.

Hummingbot Client Version

  • Make sure that you download the 2.2 branch for the Hummingbot Client.
  • Hummingbot Docker image - hummingbot/hummingbot:gateway-2.2
  • Source - git clone -b fix/gateway-2.2 https://github.com/hummingbot/hummingbot.git

Prerequisites

Install the following dependencies:

  • NodeJS (use 20.0.0 or higher)
  • Yarn: run npm install -g yarn after installing NodeJS

Installation

Clone the Gateway repo and navigate into the folder: 

git clone https://github.com/hummingbot/gateway.git
cd gateway

Switch to the legacy 2.2.0 branch

git checkout v2.2.0

Install Dependencies

Install Javascript dependencies: 

yarn install

Compile Typescript into Javascript: 

yarn build

Run Gateway

yarn start --passphrase=[PASSPHRASE]

See below to generate certifications using the passphrase above.

Generate certs

Next, generate self-signed certificates from the Hummingbot client. These certificates let your bots securely communicate with Gateway.

Start Hummingbot. After entering your password, run gateway generate-certs:

Enter a secure passphrase, and write it down. Hummingbot will generate self-signed certificates that a server can use to authenticate its connection with this client.

Take note of the certs_path where they are stored. This is also stored as certs_path in the Hummingbot's conf_client.yml, the global configuration file in the /conf/ directory.

Note that you will be prompted to enter both passphrase and certs_path later to complete the installation process.

Run setup script

The gateway-setup script, located in the root Gateway directory, performs the following actions:

  • Copies the default Gateway configuration files from /src/templates to /conf/ folder
  • Copies the Hummingbot certificates into the /certs/ folder.

Enable permissions and run setup script:

chmod a+x gateway-setup.sh
./gateway-setup.sh

When prompted, enter certs_path from the prior step:

ℹ️ Confirm if this is correct:

            Copy configs FROM: [/folder]/gateway/src/templates
              Copy configs TO: [/folder]/gateway/conf

              Copy certs FROM: [/folder]/hummingbot/certs
                Copy certs TO: [/folder]/gateway/certs

Do you want to proceed? [Y/N] >>>

Alternative to copying certs files

The gateway-setup.sh script creates a copy of the Hummingbot certificates in the Gateway folder. Alternatively, you can override the certs_path parameter in conf/server.yml and enter the path to the Hummingbot certificates.

Start Gateway

Afterwards, start Gateway using the same passphrase that you used to generate the certs:

$ yarn start --passphrase=<passphrase>

You should see Gateway running on the default port 15888: 

2023-02-09 12:56:50 | info |    ⚡️ Starting Gateway API on port 15888...
2023-02-09 12:56:50 | info |    The gateway server is secured behind HTTPS.
2023-02-09 12:56:50 | info |    ⚡️ Swagger listening on port 8080. Read the Gateway API documentation at 127.0.0.1:8080

Go back to your Hummingbot client or restart it if you have exited. In the upper right corner, you should see GATEWAY: ONLINE if your Hummingbot client is connected to Gateway.

After Gateway is running, see Testing Gateway to understand how to test the endpoints on a standalone basis before using it with Hummingbot.