diff --git a/README.md b/README.md index 62edff63b..93569d67c 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,10 @@ Please refer to the [Superalgos Desktop App](https://superalgos.org/tools-supera * [Getting Started](#getting-started) * [Before You Begin](#before-you-begin) * [The Quick Version for Experienced PC Operators](#the-quick-version-for-experienced-pc-operators) - * [The Long Version for Regular Folks on Windows and Mac](#the-long-version-for-regular-folks-on-windows-and-mac) + * [The Extended Version for Regular Folks on Windows and Mac](#the-extended-version-for-regular-folks-on-windows-and-mac) * [Downloads](#downloads/) * [Running the App](#running-the-app) + * [Running Your First Backtest](#running-your-first-backtest) * [Upgrading Your Existing Installation](#upgrading-your-existing-installation) * [Overview](#overview) * [Charts Interface](#charts-interface) @@ -107,7 +108,7 @@ The following recommendations may make your life easier using this pre-release i * We highly recommend you use Chrome to run the app, so that you have a similar environment as developers in case you need help. -* You may need a decent Console / Command Line application for similar reasons: we hope you won't need it, but in case you do, it may save you lots of hassle and make a difference troubleshooting and getting help from the community. We recommend [Console Emulator Cmder](https://cmder.net/). +* You will benefit from having a decent Console / Command Line application for similar reasons: we hope you won't need it, but in case you do, it may save you lots of hassle and make a difference troubleshooting and getting help from the community. We recommend [Console Emulator Cmder](https://cmder.net/). > Bear in mind that the app evolves fast. We do our best to keep this README up to date, however, some of the images illustrating these explanations may defer from what you will find in the app. @@ -117,99 +118,157 @@ The following recommendations may make your life easier using this pre-release i **1. Downloads**: -Download the software package from the [latest software release](https://github.com/Superalgos/DesktopApp/releases/tag/v.0.0.1-alpha) (```Superalgos-Desktop-App.zip```) and extract the file in an accessible route (you will launch the app from these folders). +Download the software package from the [latest software release](https://github.com/Superalgos/DesktopApp/releases/tag/v.0.0.2-alpha) (```Superalgos-Desktop-App.zip```) and extract the file in an accessible route (you will launch the app from these folders). -Download historic market data from the [latest data release](https://github.com/Superalgos/DesktopApp/releases/tag/data.poloniex.btc.usdt.2019.08.27) (```Poloniex.BTC.USDT.Historic.Data.zip```) and extract the file inside the ```Superalgos Desktop App``` folder generated by the software package ZIP. +Download historic market data from the [latest data release](https://github.com/Superalgos/DesktopApp/releases/tag/data.poloniex.btc.usdt.2019.09.24) (```Poloniex.BTC.USDT.Historic.Data.zip```) and extract the file inside the ```Superalgos Desktop App``` folder generated by the software ZIP package. You should end up with the following folder structure: -![image](https://user-images.githubusercontent.com/13994516/63965100-be6a7b80-ca98-11e9-9398-40b46be9ecf5.png) +![image](https://user-images.githubusercontent.com/13994516/65512836-56158b00-deda-11e9-8d81-0dcd79efb480.png) -> Make sure the data ended up as the ```Data-Storage``` folder, right inside ```Superalgos Desktop App``` +> Make sure the data ended up as the ```Data-Storage``` folder, right inside the ```Superalgos Desktop App``` root folder. **2. Continue with [Running the App](#running-the-app)** -> NOTE FOR DEVELOPERS: Instead of using the EXE file to run the app, you may want to use ```node server.js``` from within the ```WebServer``` folder to run on your full Node Js installation. +> NOTE FOR DEVELOPERS: Instead of using the executable file to run the app, you may want to use ```node run``` from within the root ```Superalgos Desktop App``` folder, to run on your full Node Js installation. -## The Long Version for Regular Folks on Windows and Mac +## The Extended Version for Regular Folks on Windows and Mac ### Downloads **1. Download the Software Package**: -Go to the [latest Superalgos Desktop App release](https://github.com/Superalgos/DesktopApp/releases/tag/v.0.0.1-alpha) and download ```Superalgos-Desktop-App.zip```. +Go to the [latest Superalgos Desktop App release](https://github.com/Superalgos/DesktopApp/releases/tag/v.0.0.2-alpha) and download ```Superalgos-Desktop-App.zip```. **2. Extract the ZIP file**: -How you extract/unpack the files depends on the software you use to handle ZIP files. Double clicking the ZIP file should work in most scenarios, however, some systems may "open" the file instead of "extracting" it. Make sure you are "extracting" and not just "opening" the file. You may also right-click the file and check the options available on the menu. +How you extract/unpack the files depends on the software you use to handle ZIP files. Double-clicking the ZIP file should work in most scenarios, however, some systems may "open" the file instead of "extracting" it. Make sure you are "extracting" and not just "opening" the file. You may also right-click the file and check the options available on the pop-up menu. When you extract the ZIP file, a folder structure will be created with the root folder being ```Superalgos Desktop App```. -You may extract/unpack the files in any location of your drive, however, we recommend unpacking in an accesible route *(i.e.: ```C:\```)*, as you will later need to fit an additional folder in the ```Superalgos Desktop App``` folder, and you will also need to access these folders every time you launch the app. +You may extract/unpack the files in any location of your drive, however, we recommend unpacking in an accessible route *(i.e.: ```C:\```)*, as you will later need to fit an additional folder inside the ```Superalgos Desktop App``` folder, and you will also need to access these folders every time you launch the app. **3. Download the Data Package**: -For your convenience and [for the reasons explained](https://superalgos.org/tools-superalgos-desktop-app.shtml#expectations) in the Superalgos Desktop App page on the website, we maintain a downloadable market data file that you can download, so that you may be up and running as quickly as possible. +For your convenience and [the reasons explained](https://superalgos.org/tools-superalgos-desktop-app.shtml#expectations) in the Superalgos Desktop App page on the website, we maintain a downloadable market-data file that you can download, so that you may be up and running as quickly as possible. -Go to the [latest Data release](https://github.com/Superalgos/DesktopApp/releases/tag/data.poloniex.btc.usdt.2019.08.27) and download ```Poloniex.BTC.USDT.Historic.Data.zip```. +Go to the [latest Data release](https://github.com/Superalgos/DesktopApp/releases/tag/data.poloniex.btc.usdt.2019.09.24) and download ```Poloniex.BTC.USDT.Historic.Data.zip```. -The ZIP file includes highly-compressed complete historic BTC/USDT market data at Poloniex. Expect decompression to take from 30 to 60 minutes, depending on your system. Once you have the historic data, the app will make sure the data stays up to date. +The ZIP file includes highly-compressed complete historic BTC/USDT Ploniex market data. Expect decompression to take from 30 to 60 minutes, depending on your system. Once you have the historic data, the app will make sure the data stays up to date. **4. Extract the ZIP file**: -You need to extract the file inside the ```Superalgos Desktop App``` folder generated by the first ZIP file. You can do this either moving ```Poloniex.BTC.USDT.Historic.Data.zip``` inside the ```Superalgos Desktop App``` folder and selecting ```Extract here``` from the menu poping up upon right-clicking the file, or by extracting anywhere else and the moving the resulting ```Data-Storage``` folder inside the ```Superalgos Desktop App``` folder. +You need to extract the file inside the ```Superalgos Desktop App``` folder generated by the first ZIP file. You can achieve this in two ways: + +A. Move ```Poloniex.BTC.USDT.Historic.Data.zip``` inside the ```Superalgos Desktop App``` folder, right-click the ZIP file and select ```Extract here``` in the pop-up menu. This is the quickest method. + +B. Extract the ZIP file anywhere else and then move the resulting ```Data-Storage``` folder inside the ```Superalgos Desktop App``` folder. This will take almost double the time. You should end up with the following folder structure: -![image](https://user-images.githubusercontent.com/13994516/63965100-be6a7b80-ca98-11e9-9398-40b46be9ecf5.png) +![image](https://user-images.githubusercontent.com/13994516/65512836-56158b00-deda-11e9-8d81-0dcd79efb480.png) -> Make sure the data ended up as the ```Data-Storage``` folder, right inside ```Superalgos Desktop App``` +> Make sure the data ended up as the ```Data-Storage``` folder, right inside the ```Superalgos Desktop App``` root folder. ### Running the App -**1. Use the executable to Run the App** +**1. Use the executable file to run the app**: -Go to ```Superalgos Desktop App\WebServer```, that is, the ```WebServer``` folder inside the ```Superalgos Desktop App``` folder and double click on ```Windows-Superalgos-Desktop.exe``` (for Windows systems) or ```MacOs-Superalgos-Desktop.app``` (for Mac systems). +Go to the ```Superalgos Desktop App``` folder and double click on ```Superalgos.exe``` (for Windows systems) or ```Superalgos.app``` (for Mac systems). -The app will load on your default browser. You should either [set Chrome as your default browser](https://support.google.com/chrome/answer/95417?co=GENIE.Platform%3DDesktop&hl=en) before executing the EXE file, or simply close the non-Chrome browser, open Chrome and go to http://localhost:1337/. +The app will load on your default browser. You should either [set Chrome as your default browser](https://support.google.com/chrome/answer/95417?co=GENIE.Platform%3DDesktop&hl=en) before executing the file or simply close the non-Chrome browser, open Chrome and go to http://localhost:1337/. Also, a Console/Command Line window will open. The Console must be open for as long as the app is running. Do not close the window or stop the processes running on it. You may minimize the Console if your Operating System allows you to do so. +> Closing the Console/Command Line may cause your market data to become corrupt. The proper way of closing the application is closing your browser first, and allow a minute for processes to stop before closing the Console. + **2. Drag and drop an example workspace**: -Go to the ```Superalgos Desktop App/Quick-Start-Examples``` folder, drag the file ```Share - Workspace - A Minimum Strategy Template.json``` and drop it on the _Designer_ (in the bottom half of the screen, the area with a black background) to start with a working template. +Go to the ```Superalgos Desktop App/Quick-Start-Examples``` folder, drag your preferred example file and drop it on the _Designer_ (the area with a black background in the bottom half of the screen) to start with a working template. -![Installation-Drag-Workspace](https://user-images.githubusercontent.com/13994516/64358772-5ae7cd00-d007-11e9-9250-77540cc351c8.gif) +![Designer-Import-Workspace](https://user-images.githubusercontent.com/13994516/65597108-a5ba8c00-df98-11e9-812d-b1e3c17ba4c8.gif) -**3. Start indicators**: +**Available Quick Start Examples**: -Click the RESTART SIMULATION button on the right-hand side of the horizontal turquoise bar. This puts all indicator bots to run. The data files you downloaded contain data files up to a certain point in time. You will need to allow some time for bots to catch up with building candles and the rest of indicators up to the present time. After a few minutes, refresh the candles layers as explained in the [Layers Panel](#layers-panel) section. +**```Share - Workspace - Bull run rider - USDT- 1hr.json```**: A functional USDT-based strategy designed for bull markets. You will be able to run a backtest and see the strategy in action if you use this template. All details about the strategy may be found in the [Superalgos/Strategy-USDT-BullRunRider](https://github.com/Superalgos/Strategy-USDT-BullRunRider) repository. + +**```Share - Workspace - Weak-hands buster - BTC - 1hr.json```**: A functional BTC-based strategy designed for accumulating bitcoin during bear markets or market consolidation situations. You will be able to run a backtest and see the strategy in action if you use this template. All details about the strategy may be found in the [Superalgos/Strategy-BTC-WeakHandsBuster](https://github.com/Superalgos/Strategy-BTC-WeakHandsBuster) repository. + +**```Share - Workspace - Empty Strategy Structure Template.json```**: A template containing the minimum set of elements required to build your own strategy. Elements are empty (undefined); this is just the structure that will guide you through the process of building your strategy. **You will not be able to run a backtest or trade live with this template until you set up your strategy.** That's it! You are up and running! -> **NOTES ON MARKET DATA AND WAITING-TIME FOR THE FIRST RUN**: The first simulation will not show on screen until the bots processing exchange data and building indicators datasets are up to date. In our experience, it may take between 10 to 20 minutes per day worth of Poloniex data to be processed. The time it will take for these processes to complete the job depends on several things: +Now you are ready to learn the basic operation of the app so that you may run your first backtests or trade live with existing strategies. + +## Running Your First Backtest + +To run your first backtest you will need a functional strategy. + +**1. Import the right template**: + +If you haven't yet, start by importing either ```Share - Workspace - Bull run rider - USDT- 1hr.json``` or ```Share - Workspace - Weak-hands buster - BTC - 1hr.json```. To do that, follow the instructions above to drag one of the files from the ```Superalgos Desktop App/Quick-Start-Examples``` folder and drop it in the *Designer* section of the app. + +**2. Start processes**: + +| Task Manager | Definition | +| :---: | :---: | +| ![task](https://user-images.githubusercontent.com/13994516/65537996-a99dce00-df06-11e9-8f02-0bd0fd6d29dd.png) | ![definition](https://user-images.githubusercontent.com/13994516/63503991-deb29d00-c4d0-11e9-8c03-bf2e618f9ef6.png) | + +Open up the Designer section of the app by dragging the horizontal bar upwards and locate the two Task Manager elements connected to the Definition element on the left-hand side of the screen. + +> To move around the Designer, click on the black background and drag to pan in the desired direction. + +Then, hover your mouse pointer over either of the Task Manager elements and click ```Run All Tasks``` in the menu. You will not see any immediate effect in your browser, but if you take a look at the Console, you will notice activity indicating that several processes are running. + +Do the same with the second Task Manager element. + +![Designer-Start-Processes](https://user-images.githubusercontent.com/13994516/65596168-9f2b1500-df96-11e9-9559-7395124c00a0.gif) + +> **NOTES ON MARKET DATA**: You just started the *Trading Engine* along with the *sensors* that extract live data from the exchange and the *indicators* that process raw trades data. These processes will remain running for as long as you keep the browser open running the app. The bots processing exchange data and building indicators datasets will work to bring your data up to date. In our experience, it may take between 10 to 20 minutes per day worth of Poloniex data to be processed. The time it will take for these processes to complete the job depends on several things: > * The date of the release tells you how many days you are behind with the data set you just downloaded. > * The speed and processing power of your machine will make a difference too. > * The average number of trades per day at the exchange determines the volume of data the app needs to retrieve and process. > * The number of trades the exchange returns per each request determines the size of the pipeline the exchanges allow API users to use. +**3. Run your first backtest**: + +Pull down the horizontal bar to go to the charts and make sure you are standing in the 1 hr (one hour) time period. Notice the time box at the bottom of the charts: + +![Getting-Started-Charts-Time-Period](https://user-images.githubusercontent.com/13994516/65598453-c0423480-df9b-11e9-9346-04631dd9719e.gif) + +If you are not, use the wheel of your mouse while pointing at the charts to scroll into the 1 hr time period. You do this so that the backtest runs in the time period for which the strategy was designed. + +You are now ready to click the START BACKTESTING button on the right-hand side of the horizontal bar. + +![Getting-Started-Backtesting](https://user-images.githubusercontent.com/13994516/65598454-c0dacb00-df9b-11e9-8e58-a149b0bffef7.gif) + +Once you click the button, it will turn yellow. It may take several minutes for the Trading Engine to do the calculations and get ready to present the simulation over the charts. Once the Trading Engine finishes, the button will turn back to its normal state. That means that you may now turn on the simulation layers in the Layers Panel. + +![Getting-Started-Backtesting02](https://user-images.githubusercontent.com/13994516/65598904-c97fd100-df9c-11e9-93f4-324979e67a2d.gif) + +You may now navigate the charts by clicking and dragging, or by zooming in and out with the wheel of your mouse. If you change the time period, you will not see the simulated data, as each time period may hold its own simulation. + +Congratulations! You've run your first simulation! + +The rest of this README file contains all the information you need to build your own strategies, modify, test and use existing ones, and eventually start trading live. + # Upgrading Your Existing Installation You should expect patches and even new releases to become available regularly. Appropriate notices will be placed on the [Official Superalgos Telegram Announcements Channel](https://t.me/superalgos), which will be forwarded to the several Community groups when this happens. If you have a version of the Superalgos Desktop App and wish to upgrade to a new version you should do the following: -**1.** Stop the app by closing your browser and the Console/Command Line running the programs. +**1.** Stop the app by closing your browser. Allow a minute or two until no activity stops before closing the Console/Command Line running the programs. **2.** Make sure you are not storing any personal files, such as your Workspace backups and so on in your ```Superalgos Desktop App``` folders. Move them to a different location if you are. -**3.** Delete all folders within the Superalgos Desktop App folder **but the ```Data-Storage``` folder**. You do not need to get rid of the historic market data every time you upgrade your app. Do **not** delete your ```Data-Storage``` folder. +**3.** You will keep the ```Data-Storage``` folder intact and delete all the remaining folders within the ```Superalgos Desktop App``` folder. You do not need to get rid of the historic market data every time you upgrade your app. **Do not delete your ```Data-Storage``` folder**. **4.** Download the latest patch or latest release from the location advertised in the Official Announcement Channel. > **WARNING**: Always beware of what random people may post in open Telegram groups or forums. Patches and releases will always be made available at the [Releases page](https://github.com/Superalgos/DesktopApp/releases) of this repository only. -**5.** Extract/unpack the contents of the ZIP file directly into the ```Superalgos Desktop App``` folder. That's it. You are up and running with the new version. Simply start the app the same way you always do. +**5.** Extract/unpack the contents of the ZIP file directly into the ```Superalgos Desktop App``` folder. That's it. You are up and running with the new version. Simply start the app the same way you always do unless new instructions become available in this README file. # Overview