diff --git a/INSTALLATION.md b/INSTALLATION.md index 9f2c6231..6e33adec 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -3,10 +3,41 @@ This repository is maintained by Hummingbot Foundation as a companion for users ## Requirements -* 8 GB memory or more (On AWS, this is a `t2.large` instance) -* Linux / Debian / MacOS +Cloud Server or local machine -## Installation +* Minimum of at least 2vCPU and 8 GB memory or more (On AWS, this is a `t2.large` instance) +* Linux / MacOS / Windows* + +* For Windows users, make sure to install WSL2 as well as a Linux distro like Ubuntu and run the commands listed below in a Linux terminal and **NOT** in the Windows Command prompt or Powershell. + +## Installation + + +### Method 1 - Deploy Repo + +This is the **recommended** install procedure for normal users + +1 - Install dependencies: + +* [Docker Engine](https://docs.docker.com/engine/install/ubuntu/) + +2 - Clone repo and navigate to the created directory +```bash +git clone https://github.com/hummingbot/deploy.git +cd deploy +``` + +3 - Run the provided bash script +```bash +bash setup.sh +``` + + +Proceed to the **Launch Dashboard** section + +### Method 2 - Source + +This method is only recommended if you are a developer and want to make changes to the code. 1 - Install dependencies: @@ -21,7 +52,7 @@ cd dashboard 3 - Create `conda` environment and install dependencies ```bash -make env_create +make install ``` 4 - Activate the isolated 'conda' environment @@ -31,123 +62,64 @@ conda activate dashboard 5 - Start the dashboard ```bash -streamlit run main.py +make run ``` -## Enable Authentication - -1 - Locate the `config.py` file in the /dashboard folder - -2 - Open the file using a text editor - -3 - Modify the `AUTH_SYSTEM_ENABLED` variable and set this to `True` to enable. By default this is set to `False` - -## Configure Credentials for Authentication -### Method 1: Using hasher_generate +Don't forget to run the **Backend-API** and **Broker** separately for this to work -1 - Update the Environment - - Ensure that you have the latest version of the project and reinstall the conda environment if needed. - -2 - Generate Hashed Password - - Open a Python terminal and utilize hasher_generate from Streamlit to generate a hashed password. Example code: +Proceed to the **Launch Dashboard** section - ``` - import streamlit_authenticator as st_auth - hashed_password = st_auth.Hasher("YOUR_PLAIN_TEXT_PASSWORD").generate()[0] - print(hashed_password) - ``` +## Launch the Dashboard -3 - Edit the Credentials YAML File +Open a web browser and navigate to to view the Dashboard. - Locate the credentials YAML file in the root directory. - Edit the file by inserting the generated hashed password from Step 2. +If you are using a cloud server or VPS, replace localhost with the IP of your server. You may need to edit the firewall rules to allow inbound connections to the necessary ports. -4 - Accessing the Dashboard - - Run the Hummingbot Dashboard project. - Use the username and the plain text password (used in Step 2) to log in to the dashboard. -5 - Logging Out - - To log out, navigate to the dashboard and select 'Logout'. - - -### Method 2: Using Pre-Authorized Emails for User Registration - -1 - Update the Environment +## Updating - As in Method 1, ensure your conda environment and project version are up-to-date. +Before updating, make sure to stop any running instances first -2 - Whitelist Emails +### Deploy Repo - In the credentials YAML file, add the emails of users who will be pre-authorized to register and create their credentials. +To update - make sure you are in the `deploy` folder then run the bash script - ``` - pre_authorized_emails: - - user1@example.com - - user2@example.com - ``` +``` +bash setup.sh +``` -3 - User Registration +This will pull any latest images and recreate the Docker containers. - Direct users to the Hummingbot Dashboard. - Users should select 'Register' and enter one of the pre-authorized email addresses. - They will choose their own username and password during registration. - -4 - First-Time Login - - Users log in with their chosen username and password. - The dashboard will hash and store their credentials automatically. +### Source -5 - Logging Out - - Similar to Method 1, users can log out by navigating to the dashboard and selecting 'Logout'. +To update the `dashboard` source for latest version, run: +``` +cd dashboard +git pull +``` -### Additional Notes +Once updated, start up the dashboard again: -- Video instruction link - https://drive.google.com/file/d/17ecd2aWHZCyuK5Etcv8AZwXMw2B-1sJG/view?usp=share_link -- Users created through Method 2 (Pre-Authorized Emails) will have their hashed passwords automatically generated and stored. -- Always ensure the secure handling and storage of credentials. -- Utilize the 'Logout' feature to secure information and restrict access to the dashboard when it is not in use. +``` +make run +``` -## Updating +To update the `dashboard` environment, run -To update the `dashboard` environment for changes to dependencies defined in `environment.yml`, remove the environment and re-create it: ``` make env_remove make env_create ``` -To updated the `dashboard` source for latest version, run: -``` -cd dashboard -git pull -``` +This will remove the `conda` environment and recreate it. ## Troubleshooting +For Dashboard issues, please open a ticket on our Dashboard [Github page](https://github.com/hummingbot/dashboard) or post in the `#hummingbot-deploy` channel in [Discord](https://discord.gg/hummingbot) + ### Docker permissions If you get an error like `Permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`, run this command to enable Docker permissions: ``` sudo chmod 6666 /var/run/docker.sock ``` - -### Sym-link data directory - -To use the [Strategy Performance page](https://github.com/hummingbot/dashboard/wiki/%F0%9F%9A%80-Strategy-Performance), you need to establish a symbolic link to the `data` directory of your running Hummingbot instance: - -The `data` directory differs for Docker versus Source installed Hummingbot: -* Docker installed: `/path/to/hummingbot/hummingbot_files/data` -* Source installed: `/path/to/hummingbot/data` - -Create a symlink to your Hummingbot `/data` directory -```bash -# replace `/path/to/hummingbotdata` with the actual path -ln -s /path/to/hummingbotdata data - -# if you need to remove the symlink -unlink data -``` diff --git a/README.md b/README.md index ff627e27..595b8f39 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Hummingbot Dashboard -Hummingbot Dashboard is an open-source application designed to assist in the creation, backtesting, and optimization of a wide variety of algorithmic trading strategies. Once refined, these strategies can be deployed as [Hummingbot](https://github.com/hummingbot/hummingbot) instances in either paper trading or live trading modes, providing a seamless transition from strategy formulation to actual trading execution. +Hummingbot Dashboard is an open-source application designed to assist in the creation, backtesting, and optimization of a wide variety of algorithmic trading strategies. Once refined, these strategies can be deployed as [Hummingbot](https://github.com/hummingbot/hummingbot) instances in live trading modes, providing a seamless transition from strategy formulation to actual trading execution. ## Features @@ -8,29 +8,17 @@ Hummingbot Dashboard is an open-source application designed to assist in the cre - **Strategy Backtesting and Optimization**: Evaluate the performance of your strategies against historical data and optimize them with Optuna - **One-Click Deployment**: Seamlessly deploy your strategies as Hummingbot instances for paper or live trading. - **Performance Analysis Monitoring**: Monitor and analyze the performance of your deployed strategies. -- **Secure Credentials**: Restrict access to whitelisted users +- **Credential Management**: Create and manage separate accounts for API keys -## Tutorial - -Get a comprehensive understanding of Hummingbot Dashboard by exploring our introductory video playlist. These videos will guide you through the various features and functionalities: - -1. [Introduction to Dashboard](https://www.youtube.com/watch?v=a-kenMqRB00&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=1) -2. [Setting up the Environment](https://www.youtube.com/watch?v=AbezIhb6iJg&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=2) -3. [Managing Credentials](https://www.youtube.com/watch?v=VmlD_WQVe4M&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=3) -4. [Using the Master Bot Profile](https://www.youtube.com/watch?v=MPQTnlDXPno&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=4) -5. [Deploying Bots and Running Strategies](https://www.youtube.com/watch?v=915E-C2LWdg&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=5) -6. Analyzing Strategy Performance (coming soon) -7. [Controllers, Backtesting, and Optimization](https://www.youtube.com/watch?v=bAi2ok7_boo&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=6) -8. [Deploying Best Strategies from Backtests](https://www.youtube.com/watch?v=BJf3ml-9JIQ&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=7) -9. [Conclusions and Next Steps](https://www.youtube.com/watch?v=ug_SSZb2HYE&list=PLDwlNkL_4MMf0Ifvj-HLuQ_Jtf7OV6uzW&index=8) - ## Documentation For detailed instructions and further information, visit our [documentation page](https://hummingbot.org/dashboard/). ## Installation -Currently, Dashboard should be installed from source via the process below. In the future, we aim to support a simpler,Docker-based installation process as well. +Currently, we recommend users to install Dashboard using the **[Deploy repo](https://github.com/hummingbot/deploy)** instead as this will automatically launch Dashboard along with the needed components in their own Docker containers. + +If you are a developer, and want to make changes to the code then we recommend using the Source installation below - please note that you will also need to launch the Backend API and Broker separately (either through source install or through Docker). 1. **Install Dependencies**: - Docker Engine @@ -44,7 +32,7 @@ Currently, Dashboard should be installed from source via the process below. In t 3. **Create Conda Environment and Install Dependencies**: ```bash - make env_create + make install ``` 4. **Activate the Isolated 'conda' Environment**: @@ -54,7 +42,7 @@ Currently, Dashboard should be installed from source via the process below. In t 5. **Start the Dashboard**: ```bash - streamlit run main.py + make run ``` For more detailed instructions on how to install and update the dashboard, refer to [INSTALLATION.md](INSTALLATION.md).