stable/docs/docker_quickstart.md

Using Freqtrade with Docker

This page explains how to run the bot with Docker. It is not meant to work out of the box. You'll still need to read through the documentation and understand how to properly configure it.

Install Docker

Start by downloading and installing Docker CE for your platform:

• Mac
• Windows
• Linux

To simplify running freqtrade, docker-compose should be installed and available to follow the below docker quick start guide.

Freqtrade with docker-compose

Freqtrade provides an official Docker image on Dockerhub, as well as a docker-compose file ready for usage.

!!! Note - The following section assumes that docker and docker-compose are installed and available to the logged in user. - All below commands use relative directories and will have to be executed from the directory containing the docker-compose.yml file.

Docker quick start

Create a new directory and place the docker-compose file in this directory.

=== "PC/MAC/Linux" ``` bash mkdir ft_userdata cd ft_userdata/ # Download the docker-compose file from the repository curl https://raw.githubusercontent.com/freqtrade/freqtrade/stable/docker-compose.yml -o docker-compose.yml

# Pull the freqtrade image
docker-compose pull

# Create user directory structure
docker-compose run --rm freqtrade create-userdir --userdir user_data

# Create configuration - Requires answering interactive questions
docker-compose run --rm freqtrade new-config --config user_data/config.json
```

=== "RaspberryPi" ``` bash mkdir ft_userdata cd ft_userdata/ # Download the docker-compose file from the repository curl https://raw.githubusercontent.com/freqtrade/freqtrade/stable/docker-compose.yml -o docker-compose.yml

# Edit the compose file to use an image named `*_pi` (stable_pi or develop_pi)

# Pull the freqtrade image
docker-compose pull

# Create user directory structure
docker-compose run --rm freqtrade create-userdir --userdir user_data

# Create configuration - Requires answering interactive questions
docker-compose run --rm freqtrade new-config --config user_data/config.json
```

!!! Note "Change your docker Image"
    You have to change the docker image in the docker-compose file for your Raspberry build to work properly.
    ``` yml
    image: freqtradeorg/freqtrade:stable_pi
    # image: freqtradeorg/freqtrade:develop_pi
    ```

=== "ARM 64 Systenms (Mac M1, Raspberry Pi 4, Jetson Nano)" In case of a Mac M1, make sure that your docker installation is running in native mode Arm64 images are not yet provided via Docker Hub and need to be build locally first. Depending on the device, this may take a few minutes (Apple M1) or multiple hours (Raspberry Pi)

``` bash
# Clone Freqtrade repository
git clone  https://github.com/freqtrade/freqtrade.git
cd freqtrade
# Optionally switch to the stable version
git checkout stable   

# Modify your docker-compose file to enable building and change the image name 
# (see the Note Box below for necessary changes)

# Build image
docker-compose build

# Create user directory structure
docker-compose run --rm freqtrade create-userdir --userdir user_data

# Create configuration - Requires answering interactive questions
docker-compose run --rm freqtrade new-config --config user_data/config.json
```

!!! Note "Change your docker Image"
    You have to change the docker image in the docker-compose file for your arm64 build to work properly.
    ``` yml
    image: freqtradeorg/freqtrade:custom_arm64
    build:
      context: .
      dockerfile: "Dockerfile"
    ```

The above snippet creates a new directory called ft_userdata, downloads the latest compose file and pulls the freqtrade image. The last 2 steps in the snippet create the directory with user_data, as well as (interactively) the default configuration based on your selections.

!!! Question "How to edit the bot configuration?" You can edit the configuration at any time, which is available as user_data/config.json (within the directory ft_userdata) when using the above configuration.

You can also change the both Strategy and commands by editing the command section of your `docker-compose.yml` file.

Adding a custom strategy

1. The configuration is now available as user_data/config.json
2. Copy a custom strategy to the directory user_data/strategies/
3. Add the Strategy' class name to the docker-compose.yml file

The SampleStrategy is run by default.

!!! Warning "SampleStrategy is just a demo!" The SampleStrategy is there for your reference and give you ideas for your own strategy. Please always backtest your strategy and use dry-run for some time before risking real money! You will find more information about Strategy development in the Strategy documentation.

Once this is done, you're ready to launch the bot in trading mode (Dry-run or Live-trading, depending on your answer to the corresponding question you made above).

docker-compose up -d

!!! Warning "Default configuration" While the configuration generated will be mostly functional, you will still need to verify that all options correspond to what you want (like Pricing, pairlist, ...) before starting the bot.

Monitoring the bot

You can check for running instances with docker-compose ps. This should list the service freqtrade as running. If that's not the case, best check the logs (see next point).

Docker-compose logs

Logs will be written to: user_data/logs/freqtrade.log.
You can also check the latest log with the command docker-compose logs -f.

Database

The database will be located at: user_data/tradesv3.sqlite

Updating freqtrade with docker-compose

Updating freqtrade when using docker-compose is as simple as running the following 2 commands:

# Download the latest image
docker-compose pull
# Restart the image
docker-compose up -d

This will first pull the latest image, and will then restart the container with the just pulled version.

!!! Warning "Check the Changelog" You should always check the changelog for breaking changes / manual interventions required and make sure the bot starts correctly after the update.

Editing the docker-compose file

Advanced users may edit the docker-compose file further to include all possible options or arguments.

All freqtrade arguments will be available by running docker-compose run --rm freqtrade <command> <optional arguments>.

!!! Note "docker-compose run --rm" Including --rm will remove the container after completion, and is highly recommended for all modes except trading mode (running with freqtrade trade command).

Example: Download data with docker-compose

Download backtesting data for 5 days for the pair ETH/BTC and 1h timeframe from Binance. The data will be stored in the directory user_data/data/ on the host.

docker-compose run --rm freqtrade download-data --pairs ETH/BTC --exchange binance --days 5 -t 1h

Head over to the Data Downloading Documentation for more details on downloading data.

Example: Backtest with docker-compose

Run backtesting in docker-containers for SampleStrategy and specified timerange of historical data, on 5m timeframe:

docker-compose run --rm freqtrade backtesting --config user_data/config.json --strategy SampleStrategy --timerange 20190801-20191001 -i 5m

Head over to the Backtesting Documentation to learn more.

Additional dependencies with docker-compose

If your strategy requires dependencies not included in the default image - it will be necessary to build the image on your host. For this, please create a Dockerfile containing installation steps for the additional dependencies (have a look at docker/Dockerfile.custom for an example).

You'll then also need to modify the docker-compose.yml file and uncomment the build step, as well as rename the image to avoid naming collisions.

    image: freqtrade_custom
    build:
      context: .
      dockerfile: "./Dockerfile.<yourextension>"

You can then run docker-compose build to build the docker image, and run it using the commands described above.

Plotting with docker-compose

Commands freqtrade plot-profit and freqtrade plot-dataframe (Documentation) are available by changing the image to *_plot in your docker-compose.yml file. You can then use these commands as follows:

docker-compose run --rm freqtrade plot-dataframe --strategy AwesomeStrategy -p BTC/ETH --timerange=20180801-20180805

The output will be stored in the user_data/plot directory, and can be opened with any modern browser.

Data analysis using docker compose

Freqtrade provides a docker-compose file which starts up a jupyter lab server. You can run this server using the following command:

docker-compose -f docker/docker-compose-jupyter.yml up

This will create a docker-container running jupyter lab, which will be accessible using https://127.0.0.1:8888/lab. Please use the link that's printed in the console after startup for simplified login.

Since part of this image is built on your machine, it is recommended to rebuild the image from time to time to keep freqtrade (and dependencies) up-to-date.

docker-compose -f docker/docker-compose-jupyter.yml build --no-cache