Official Chia Docker Container

Quick Start

These examples shows valid setups using Chia for both docker run and docker-compose. Note that you should read some documentation at some point, but this is a good place to start.

Docker run

Simple example:

docker run --name chia --expose=8444 -v /path/to/plots:/plots -d ghcr.io/chia-network/chia:latest

Syntax

docker run [--name <container-name>] [--expose=<port>] [-v </path/to/plots:/plots>] -d ghcr.io/chia-network/chia:latest

Optional Docker parameters:

• Give the container a name: --name=chia
• Accept incoming connections: --expose=8444
• Volume mount plots: -v /path/to/plots:/plots

Docker compose

version: "3.6"
services:
  chia:
    container_name: chia
    restart: unless-stopped
    image: ghcr.io/chia-network/chia:latest
    ports:
      - 8444:8444
    volumes:
      - /path/to/plots:/plots

Configuration

You can modify the behavior of your Chia container by setting specific environment variables.

Timezone

Set the timezone for the container (optional, defaults to UTC). Timezones can be configured using the TZ env variable. A list of supported time zones can be found here

-e TZ="America/Chicago"

Add your custom keys

To use your own keys pass a file with your mnemonic as arguments on startup

-v /path/to/key/file:/path/in/container -e keys="/path/in/container"

or pass keys into the running container with your mnemonic

docker exec -it <container-name> venv/bin/chia keys add

alternatively you can pass in your local keychain, if you have previously deployed chia with these keys on the host machine

-v ~/.local/share/python_keyring/:/root/.local/share/python_keyring/

or if you would like to persist the entire mainnet subdirectory and not touch the key directories at all

-v ~/.chia/mainnet:/root/.chia/mainnet -e keys="persistent"

Persist configuration, db, and keyring

You can persist whole db and configuration, simply mount it to Host.

-v ~/.chia:/root/.chia \
-v ~/.chia_keys:/root/.chia_keys

Farmer only

To start a farmer only node pass

-e service="farmer-only"

Harvester only

To start a harvester only node pass

-e service="harvester" -e farmer_address="addres.of.farmer" -e farmer_port="portnumber" -v /path/to/ssl/ca:/path/in/container -e ca="/path/in/container" -e keys="none"

Configure full_node peer

To set the full_node peer's hostname and port, set the "full_node_peer" environment variable with the format hostname:port

-e full_node_peer="node:8444"

This will configure the full_node peer hostname and port for the wallet, farmer, and timelord sections of the config.yaml file.

Plots

The plots_dir environment variable can be used to specify the directory containing the plots, it supports PATH-style colon-separated directories.

Or, you can simply mount /plots path to your host machine.

Set the environment variable recursive_plot_scan to true to enable the recursive plot scan configuration option.

Adding mounts while running

By default, Docker requires a container restart to discover newly mounted filesystems under a configured bind-mount. Setting the bind-propagation option to rslave enables dynamic addition of sub-mounts while the container is running (Linux systems only). See Docker Bind Mounts documentation for more information.

-v /plotdrives:/plotdrives:rslave

Compressed Plots

There are a few environment variables that control compressed plot settings for Harvesters ran with chia-docker. The default settings leave compressed plot harvesting disabled, but it can be enabled.

See the official documentation for a description on what each of these settings do.

Compressed plot farming can be enabled by setting the following:

-e parallel_decompressor_count=1
-e decompressor_thread_count=1

And to use an nvidia GPU for plot decompression, set:

-e use_gpu_harvesting="true"

Log level

To set the log level to one of CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET

-e log_level="DEBUG"

Peer Count

To set the peer_count and outbound_peer_count

for example to set both to 20 use

-e peer_count="20"

-e outbound_peer_count="20"

UPnP

To disable UPnP support (enabled by default)

-e upnp="false"

Log to file

Log file can be used by external tools like chiadog, etc. Enabled by default.

To disable log file generation, use

-e log_to_file="false"

Docker Compose

version: "3.6"
services:
  chia:
    container_name: chia
    restart: unless-stopped
    image: ghcr.io/chia-network/chia:latest
    ports:
      - 8444:8444
    environment:
      # Farmer Only
#     service: farmer-only
      # Harvester Only
#     service: harvester
#     farmer_address: 192.168.0.10
#     farmer_port: 8447
#     ca: /path/in/container
#     keys: generate
      # Harvester Only END
      # If you would like to add keys manually via mnemonic file
#     keys: /path/in/container
      # OR
      # Disable key generation on start
#     keys: 
      TZ: ${TZ}
      # Enable UPnP
#     upnp: "true"
      # Enable log file generation
#     log_to_file: "true"
    volumes:
      - /path/to/plots:/plots
      - /home/user/.chia:/root/.chia
#     - /home/user/mnemonic:/path/in/container

CLI

You can run commands externally with venv (this works for most chia CLI commands)

docker exec -it chia venv/bin/chia plots add -d /plots

Is it working?

You can see status from outside the container

docker exec -it chia venv/bin/chia show -s -c

or

docker exec -it chia venv/bin/chia farm summary

Connect to testnet?

docker run -d --expose=58444 -e testnet=true --name chia ghcr.io/chia-network/chia:latest

Connect remotely

Sometimes you may want to access Chia RPCs from outside of the container, or connect a GUI to a remote Chia farm. In those instances, you may need to configure the self_hostname key in the Chia config file.

By default this is set to 127.0.0.1 in chia-docker, but can be configured using the self_hostname environment variable, like so:

docker run -d -e self_hostname="0.0.0.0" --name chia ghcr.io/chia-network/chia:latest

This sets self_hostname in the config to 0.0.0.0, which will allow you to access the Chia RPC from outside of the container (you will still need a copy of the private cert/key for the component you're attempting to access.)

Need a wallet?

To get new wallet, execute command and follow the prompts:

docker exec -it chia-farmer1 venv/bin/chia wallet show

Building

docker build -t chia --build-arg BRANCH=latest .

Healthchecks

The Dockerfile includes a HEALTHCHECK instruction that runs one or more curl commands against the Chia RPC API. In Docker, this can be disabled using an environment variable -e healthcheck=false as part of the docker run command. Or in docker-compose you can add it to your Chia service, like so:

version: "3.6"
services:
  chia:
    ...
    environment:
      healthcheck: "false"

In Kubernetes, Docker healthchecks are disabled by default. Instead, readiness and liveness probes should be used, which can be configured in a Pod or Deployment manifest file like the following:

livenessProbe:
  exec:
    command:
    - /bin/sh
    - -c
    - '/usr/local/bin/docker-healthcheck.sh || exit 1'
  initialDelaySeconds: 60
readinessProbe:
  exec:
    command:
    - /bin/sh
    - -c
    - '/usr/local/bin/docker-healthcheck.sh || exit 1'
  initialDelaySeconds: 60

See Configure Probes for more information about configuring readiness and liveness probes for Kubernetes clusters. The initialDelaySeconds parameter may need to be adjusted higher or lower depending on the speed to start up on the host the container is running on.