diff --git a/docs/installation.md b/docs/installation.md index 317d149fc..d2661f88f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,22 +2,20 @@ This page explains how to prepare your environment for running the bot. -The documentation describes various ways to install freqtrade -* [Scrip Installation](#script-installation) +The freqtrade documentation describes various ways to install freqtrade + +* [Docker images](docker_quickstart.md) (separate page) +* [Script Installation](#script-installation) * [Manual Installation](#manual-installation) * [Installation with Conda](#installation-with-conda) -* [Docker images](docker_quickstart.md) (separate page) Please consider using the prebuilt [docker images](docker_quickstart.md) to get started quickly while evaluating how freqtrade works. ------ -### Information +## Information -#### Set of Notes - -!!! Note - Windows installation is explained [here](#windows). +For Windows installation, please use the [windows installation guide](windows_installation.md). The easiest way to install and run Freqtrade is to clone the bot Github repository and then run the `./setup.sh` script, if it's available for your platform. @@ -34,23 +32,19 @@ The easiest way to install and run Freqtrade is to clone the bot Github reposito ------ -### Requirements +## Requirements -This is set of requirements for both: -* [Scrip Installation](#script-installation) -* [Manual Installation](#manual-installation) +These requirements apply to both [Script Installation](#script-installation) and [Manual Installation](#manual-installation). -#### Install guide: +### Install guide * [Python >= 3.7.x](http://docs.python-guide.org/en/latest/starting/installation/) * [pip](https://pip.pypa.io/en/stable/installing/) * [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) * [virtualenv](https://virtualenv.pypa.io/en/stable/installation.html) (Recommended) -* [TA-Lib](https://mrjbq7.github.io/ta-lib/install.html) (install instructions below) +* [TA-Lib](https://mrjbq7.github.io/ta-lib/install.html) (install instructions [below](#install-ta-lib)) - We also recommend a [Telegram bot](telegram-usage.md#setup-your-telegram-bot), which is optional but recommended. - -#### Install code +### Install code We've included/collected install instructions for Ubuntu, MacOS, and Windows. These are guidelines and your success may vary with other distros. OS Specific steps are listed first, the [Common](#common) section below is necessary for all systems. @@ -66,11 +60,7 @@ OS Specific steps are listed first, the [Common](#common) section below is neces sudo apt-get update # install packages - sudo apt install -y python3-pip \ - python3-venv \ - python3-pandas \ - python3-pip \ - git + sudo apt install -y python3-pip python3-venv python3-pandas python3-pip git ``` === "RaspberryPi/Raspbian" @@ -93,18 +83,17 @@ OS Specific steps are listed first, the [Common](#common) section below is neces !!! Note "Installation duration" Depending on your internet speed and the Raspberry Pi version, installation can take multiple hours to complete. - Due to this, we recommend to use the prebuild docker-image for Raspberry, by following the [Docker quickstart documentation](docker_quickstart.md) + Due to this, we recommend to use the pre-build docker-image for Raspberry, by following the [Docker quickstart documentation](docker_quickstart.md) !!! Note The above does not install hyperopt dependencies. To install these, please use `python3 -m pip install -e .[hyperopt]`. We do not advise to run hyperopt on a Raspberry Pi, since this is a very resource-heavy operation, which should be done on powerful machine. - ------ -### Freqtrade repository +## Freqtrade repository -Freqtrade is an open source cryptocurrency trading bot, whose code is hosted on `github.com` +Freqtrade is an open source crypto-currency trading bot, whose code is hosted on `github.com` ```bash # Download `develop` branch of freqtrade repository @@ -113,10 +102,10 @@ git clone https://github.com/freqtrade/freqtrade.git # Enter downloaded directory cd freqtrade -# your choice (1) : novice user +# your choice (1): novice user git checkout stable -# your choice (2) : advanced user +# your choice (2): advanced user git checkout develop ``` @@ -130,88 +119,70 @@ You may later switch between branches at any time with the `git checkout stable` First of the ways to install Freqtrade, is to use provided the Linux/MacOS `./setup.sh` script, which install all dependencies and help you configure the bot. -#### Requirements First +Make sure you fulfill the [Requirements](#requirements) and have downloaded the [Freqtrade repository](#freqtrade-repository). -First fill the [Requirements](#requirements) +### Use /setup.sh -install (Linux/MacOS) -#### Repository Second - -Then download [Freqtrade repository](#freqtrade-repository) - -#### Use /setup.sh -install (Linux/MacOS) - -If you are on Debian, Ubuntu or MacOS Freqtrade provides the script to install freqtrade. +If you are on Debian, Ubuntu or MacOS, freqtrade provides the script to install freqtrade. ```bash # --install, Install freqtrade from scratch ./setup.sh -i ``` -#### Activate your virtual environment -Each time you open a new terminal, you must run `source .env/bin/activate`. +### Activate your virtual environment + +Each time you open a new terminal, you must run `source .env/bin/activate` to activate your virtual environment. ```bash # then activate your .env source ./.env/bin/activate ``` -### Bravo! +### Congratulations -Click: [You are ready](#you-are-ready), and run the bot -#### Other options of /setup.sh script +### Other options of /setup.sh script -You can as well update, configure and reset the codebase of your bot with /script.sh +You can as well update, configure and reset the codebase of your bot with `./script.sh` ```bash # --update, Command git pull to update. ./setup.sh -u # --reset, Hard reset your develop/stable branch. ./setup.sh -r - -# --config, Easy config generator (Will override your existing file). -./setup.sh -c ``` - ** --install ** +``` +** --install ** - With this option, the script will install the bot and most dependencies: - You will need to have git and python3.7+ installed beforehand for this to work. +With this option, the script will install the bot and most dependencies: +You will need to have git and python3.7+ installed beforehand for this to work. - * Mandatory software as: `ta-lib` - * Setup your virtualenv under `.env/` +* Mandatory software as: `ta-lib` +* Setup your virtualenv under `.env/` - This option is a combination of installation tasks, `--reset` and `--config`. +This option is a combination of installation tasks and `--reset` - ** --update ** +** --update ** - This option will pull the last version of your current branch and update your virtualenv. Run the script with this option periodically to update your bot. +This option will pull the last version of your current branch and update your virtualenv. Run the script with this option periodically to update your bot. - ** --reset ** - - This option will hard reset your branch (only if you are on either `stable` or `develop`) and recreate your virtualenv. - - ** --config ** - - DEPRECATED - use `freqtrade new-config -c config.json` instead. +** --reset ** +This option will hard reset your branch (only if you are on either `stable` or `develop`) and recreate your virtualenv. +``` ----- ## Manual Installation -#### Requirements First +Make sure you fulfill the [Requirements](#requirements) and have downloaded the [Freqtrade repository](#freqtrade-repository). -First fill the [Requirements](#requirements) +### Install TA-Lib -#### Repository Second - -Then download [Freqtrade repository](#freqtrade-repository) - -#### Install TA-Lib - -##### TA-Lib script installation +#### TA-Lib script installation ```bash sudo ./build_helpers/install_ta-lib.sh @@ -255,15 +226,14 @@ python3 -m pip install --upgrade pip python3 -m pip install -e . ``` -### Bravo! +### Congratulations -Click: [You are ready](#you-are-ready), and run the bot #### (Optional) Post-installation Tasks -*Note*: If you run the bot on a server, you should consider using [Docker](docker.md) or a terminal multiplexer like `screen` or [`tmux`](https://en.wikipedia.org/wiki/Tmux) to avoid that the bot is stopped on logout. - +!!! Note + If you run the bot on a server, you should consider using [Docker](docker_quickstart.md) or a terminal multiplexer like `screen` or [`tmux`](https://en.wikipedia.org/wiki/Tmux) to avoid that the bot is stopped on logout. On Linux with software suite `systemd`, as an optional post-installation task, you may wish to setup the bot to run as a `systemd service` or configure it to send the log messages to the `syslog`/`rsyslog` or `journald` daemons. See [Advanced Logging](advanced-setup.md#advanced-logging) for details. @@ -273,12 +243,11 @@ On Linux with software suite `systemd`, as an optional post-installation task, y Freqtrade can also be installed with Miniconda or Anaconda. We recommend using Miniconda as it's installation footprint is smaller. Conda will automatically prepare and manage the extensive library-dependencies of the Freqtrade program. -##### What is Conda? +### What is Conda? -It is: (1) package, (2) dependency and (3) environment management for any programming language : https://docs.conda.io/projects/conda/en/latest/index.html +Conda is a package, dependency and environment manager for multiple programming languages: [conda docs](https://docs.conda.io/projects/conda/en/latest/index.html) - -### Installation +### Installation with conda #### Install Conda @@ -300,7 +269,7 @@ git clone https://github.com/freqtrade/freqtrade.git cd freqtrade ``` -#### Freqtrade install : Conda Environment +#### Freqtrade instal: Conda Environment Prepare conda-freqtrade environment, using file `environment.yml`, which exist in main freqtrade directory @@ -308,7 +277,18 @@ Prepare conda-freqtrade environment, using file `environment.yml`, which exist i conda env create -n freqtrade-conda -f environment.yml ``` -#### Enter/exit freqtrade-conda venv: +!!! Note "Creating Conda Environment" + The conda command `create -n` automatically installs all nested dependencies for the selected libraries, general structure of installation command is: + + ```bash + # choose your own packages + conda env create -n [name of the environment] [python version] [packages] + + # point to file with packages + conda env create -n [name of the environment] -f [file] + ``` + +#### Enter/exit freqtrade-conda environment To check available environments, type @@ -322,7 +302,7 @@ Enter installed environment # enter conda environment conda activate freqtrade-conda -# exit conda environment - don`t do it now +# exit conda environment - don't do it now conda deactivate ``` @@ -333,10 +313,8 @@ python3 -m pip install --upgrade pip python3 -m pip install -e . ``` +### Congratulations -### Bravo! - -Click: [You are ready](#you-are-ready), and run the bot ### Important shortcuts @@ -355,74 +333,30 @@ conda activate freqtrade-conda conda deactivate ``` -### Notes - -#### Set of Notes 1 - Conda Settings - -After opening terminal, you already will be in default `base` conda environment. -If you want, you can prevent the (base) conda environment from being activated automatically. - -```bash -conda config --set auto_activate_base false -``` - -Channel `conda-forge` is supposingly best source of the conda updates. Switch to it - -```bash -# adding forge -conda config --env --add channels conda-forge - -# make it strict -conda config --env --set channel_priority strict - -# check status of your conda -conda info -conda config --show channels -conda config --show channel_priority -``` - -Further read on the topic: - -https://towardsdatascience.com/a-guide-to-conda-environments-bc6180fc533?gi=1db972389cd1 - -#### Set of Notes 2 - Conda Environment - -!!! Note "Creating Conda Environment" - The conda command `create -n` automatically installs all nested dependencies for the selected libraries, general structure of installation command is: - -```bash -# choose your own packages -conda env create -n [name of the environment] [python version] [packages] - -# point to file with packages -conda env create -n [name of the environment] -f [file] -``` +### Further info on anaconda !!! Info "New heavy packages" - It may happen that creating a new Conda environment, populated with selected packages at the moment of creation, takes less time than installing a large, heavy dependent, GUI package, into previously set environment. Great example: Spyder + It may happen that creating a new Conda environment, populated with selected packages at the moment of creation takes less time than installing a large, heavy library or application, into previously set environment. !!! Warning "pip install within conda" - Please read the section [Market order pricing](#market-order-pricing) section when using market orders. - The documentation of conda says that pip should NOT be used within conda, because internal problems can occur. - However, they are rare. https://www.anaconda.com/blog/using-pip-in-a-conda-environment + However, they are rare. [Anaconda Blogpost](https://www.anaconda.com/blog/using-pip-in-a-conda-environment) - Nevertherless, that is why, the `conda-forge` channel is preferred: + Nevertheless, that is why, the `conda-forge` channel is preferred: * more libraries are available (less need for `pip`) * `conda-forge` works better with `pip` * the libraries are newer - Happy trading! ----- ## You are ready -You had installed the bot +You've made it this far, so you have successfully installed freqtrade. -#### Initialize the configuration +### Initialize the configuration ```bash # Step 1 - Initialize user folder @@ -432,19 +366,24 @@ freqtrade create-userdir --userdir user_data freqtrade new-config --config config.json ``` -You are ready to run, read [Bot Configuration](configuration.md), remember to run program as `dry_run: True` and verify that everything is working. +You are ready to run, read [Bot Configuration](configuration.md), remember to start with `dry_run: True` and verify that everything is working. +To learn how to setup your configuration, please refer to the [Bot Configuration](configuration.md) documentation page. -> *To edit the config please refer to [Bot Configuration](configuration.md).* - - -#### Run the Bot +### Start the Bot ```bash -freqtrade trade -c config.json +freqtrade trade --config config.json --strategy SampleStrategy ``` -#### Problem? +!!! Warning + You should read through the rest of the documentation, backtest the strategy you're going to use, and use dry-run before enabling trading with real money. + +----- + +## Troubleshooting + +### Common problem: "command not found" If you used (1)`Script` or (2)`Manual` installation, you need to run the bot in virtual environment. If you get error as below, make sure venv is active. @@ -456,9 +395,6 @@ bash: freqtrade: command not found source ./.env/bin/activate ``` ------ -## Troubleshooting - ### MacOS installation error Newer versions of MacOS may have installation failed with errors like `error: command 'g++' failed with exit status 1`. @@ -484,8 +420,3 @@ brew install hdf5 c-blosc ``` After this, please run the installation (script) again. - ------ - -Now you have an environment ready, the next step is -[Bot Configuration](configuration.md).