diff --git a/Dockerfile b/Dockerfile index 047144d21a..20eede1c84 100644 --- a/Dockerfile +++ b/Dockerfile @@ -32,5 +32,6 @@ RUN export SUBNET_EVM_COMMIT=$SUBNET_EVM_COMMIT && export CURRENT_BRANCH=$CURREN FROM $AVALANCHEGO_NODE_IMAGE AS builtImage # Copy the evm binary into the correct location in the container +ENV AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ ARG VM_ID=srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy COPY --from=builder /build/build/subnet-evm /avalanchego/build/plugins/$VM_ID diff --git a/README.md b/README.md index 9b22a32acc..a0a0ba0383 100644 --- a/README.md +++ b/README.md @@ -98,3 +98,75 @@ There are two options when using the Avalanche-CLI: 1. Use an official Subnet-EVM release: https://docs.avax.network/subnets/build-first-subnet 2. Build and deploy a locally built (and optionally modified) version of Subnet-EVM: https://docs.avax.network/subnets/create-custom-subnet + +## Run in Docker + +The `subnet-evm` Docker image comes with AvalancheGo pre-installed, making it easy to run a node. You can find the latest image tags on [Docker Hub](https://hub.docker.com/r/avaplatform/subnet-evm/tags). + +### Configuration + +You can configure the `subnet-evm` Docker container using environment variables, flags or standard AvalancheGo config files. + +- **Environment Variables**: Use uppercase variables prefixed with `AVAGO_`. For example, `AVAGO_NETWORK_ID` corresponds to the `--network-id` [flag in AvalancheGo](https://docs.avax.network/nodes/configure/configs-flags#--network-id-string). +- **Flags**: Please refer to the [AvalancheGo documentation](https://docs.avax.network/nodes/configure/configs-flags) for a list of available flags. +- **Config Files**: Configure as you would with the regular AvalancheGo binary using config files. Mount the config directory with `-v ~/.avalanchego:/root/.avalanchego`. + +### Data Persistence + +To persist data across container restarts, you need to mount the `/root/.avalanchego` directory. For example, `-v ~/.avalanchego:/root/.avalanchego`. The container runs as root by default. + +### Updating + +Run `docker stop avago; docker rm avago;` then start a new container with the latest version tag in your `docker run` command. + +### Networking + +Using `--network host` is recommended to avoid any issues. +If you know what you are doing, you will need port `AVAGO_STAKING_PORT` (default `9651`) open for the validator to connect to the subnet. For the RPC server, open `AVAGO_HTTP_PORT` (default `9650`). Do not attempt to remap `AVAGO_STAKING_PORT` using the Docker `-p` flag (e.g., `-p 9651:1234`); it will not work. Instead, set `AVAGO_STAKING_PORT=1234` and then use `-p 1234:1234`. + +This is because the staking port is used for peer-to-peer communication between validators, and the port number is part of the node's identity in the network. If you remap it using Docker's port mapping, other nodes will still try to connect to the original port number advertised by your node, leading to connection failures. The HTTP port can be remapped freely since it's only used for API calls. + +### Example Configs + +#### Fuji Subnet Validator + +```bash +docker run -it -d \ + --name avago \ + --network host \ + -v ~/.avalanchego:/home/avalanche/.avalanchego \ + -e AVAGO_NETWORK_ID=fuji \ + -e AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK=true \ + -e AVAGO_TRACK_SUBNETS=REPLACE_THIS_WITH_YOUR_SUBNET_ID \ + -e AVAGO_PUBLIC_IP_RESOLUTION_SERVICE=ifconfigme \ + avaplatform/subnet-evm:v0.7.1-rc.0 +``` + +- `AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK`: Ensures you don't sync the X and C-Chains. +- `AVAGO_TRACK_SUBNETS`: Sets the subnet ID to track. It will track all chains in the subnet. +- `AVAGO_NETWORK_ID=fuji`: Sets the network ID to Fuji. Remove to sync Mainnet. +- `AVAGO_PUBLIC_IP_RESOLUTION_SERVICE=ifconfigme`: Required for AWS EC2 instances to be accessed from outside AWS. + +#### Fuji Subnet RPC + +```bash +docker run -it -d \ + --name rpc \ + --network host \ + -v ~/.avalanchego_rpc/:/home/avalanche/.avalanchego \ + -e AVAGO_NETWORK_ID=fuji \ + -e AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK=true \ + -e AVAGO_TRACK_SUBNETS=hk755meusfKqBb9C9RfzzCxZFkdSXhaFHTcbtycMUSQ11o2cd \ + -e AVAGO_HTTP_PORT=8080 \ + -e AVAGO_STAKING_PORT=9653 \ + -e AVAGO_HTTP_ALLOWED_HOSTS="*" \ + -e AVAGO_HTTP_HOST=0.0.0.0 \ + -e AVAGO_PUBLIC_IP_RESOLUTION_SERVICE=ifconfigme \ + avaplatform/subnet-evm:v0.7.1-rc.0 +``` + +- `AVAGO_STAKING_PORT` is set to `9653` in case you want to run this on the same machine as the validator. Remove this to set to the default `9651`. +- `AVAGO_HTTP_PORT` is set to `8080` instead of `9650` to avoid conflicts with the validator. +- `AVAGO_HTTP_ALLOWED_HOSTS` and `AVAGO_HTTP_HOST` are required to allow the RPC server to be accessed from outside. You'll need to secure it with HTTPS; Caddy is recommended. + +RPC example uses another folder `~/.avalanchego_rpc` to avoid conflicts with the validator if you want to run both on the same machine.