From eadcde3e9b804c0ced347e4406d9be15783e1c76 Mon Sep 17 00:00:00 2001 From: Containerman17 <8990432+containerman17@users.noreply.github.com> Date: Thu, 16 Jan 2025 04:29:22 +0000 Subject: [PATCH 1/6] docker readme --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/README.md b/README.md index 30bdfb31ab..9d6b18830e 100644 --- a/README.md +++ b/README.md @@ -98,3 +98,80 @@ 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 + +### Configuration + +You can configure the `subnet-evm` Docker container using both environment variables and 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. +- **Config Files**: Configure as you would with the regular AvalancheGo binary using config files. Ensure `HOME` is set to `/home/avalanche` and mount the config directory with `-v ~/.avalanchego:/home/avalanche/.avalanchego`. + +### Data Persistence + +To persist data across container restarts, you need to mount the `.avalanchego` directory. + +- **Create Directory**: Run `mkdir -p ~/.avalanchego/staking` beforehand to create the necessary directories and avoid file system access issues. +- **Set Permissions**: Run the container with `--user $(id -u):$(id -g)` to ensure proper access rights. +- **Set Home and Mount**: Set `HOME` to `/home/avalanche` and mount the data directory with `-v ~/.avalanchego:/home/avalanche/.avalanchego`. + +### 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`. + +### Example Configs + +#### Fuji Subnet Validator + +```bash +mkdir -p ~/.avalanchego/staking; 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 \ + -e AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ \ + -e HOME=/home/avalanche \ + --user $(id -u):$(id -g) \ + avaplatform/subnet-evm:v0.7.1 +``` + +- `AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK`: Ensures you don't sync the X and C-Chains. +- `AVAGO_PLUGIN_DIR`: Sets the directory for the `subnet-evm` plugin. +- `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 +const dockerCommand = (subnetID: string, chainID: string) => `mkdir -p ~/.avalanchego_rpc/staking; 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=REPLACE_THIS_WITH_YOUR_SUBNET_ID \\ + -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 \\ + -e AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ \\ + -e HOME=/home/avalanche \\ + --user $(id -u):$(id -g) \\ + avaplatform/subnet-evm:v0.7.1`; +``` + +- `AVAGO_STAKING_PORT` is set to `9653` in case you want to run this on the same machine as the validator. +- `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. From ec42aa7d2345d362ab36b0fbd98bb60dffe36332 Mon Sep 17 00:00:00 2001 From: Containerman17 <8990432+containerman17@users.noreply.github.com> Date: Thu, 16 Jan 2025 04:36:21 +0000 Subject: [PATCH 2/6] fix Fuji Subnet RPC example --- README.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 9d6b18830e..cfd9c90eba 100644 --- a/README.md +++ b/README.md @@ -154,24 +154,26 @@ mkdir -p ~/.avalanchego/staking; docker run -it -d \ #### Fuji Subnet RPC ```bash -const dockerCommand = (subnetID: string, chainID: string) => `mkdir -p ~/.avalanchego_rpc/staking; 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=REPLACE_THIS_WITH_YOUR_SUBNET_ID \\ - -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 \\ - -e AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ \\ - -e HOME=/home/avalanche \\ - --user $(id -u):$(id -g) \\ - avaplatform/subnet-evm:v0.7.1`; +mkdir -p ~/.avalanchego_rpc/staking; 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=REPLACE_THIS_WITH_YOUR_SUBNET_ID \ + -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 \ + -e AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ \ + -e HOME=/home/avalanche \ + --user $(id -u):$(id -g) \ + avaplatform/subnet-evm:v0.7.1 ``` - `AVAGO_STAKING_PORT` is set to `9653` in case you want to run this on the same machine as the validator. - `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. From d4077ea7fec9a155b8f2952dd02b1598f4309986 Mon Sep 17 00:00:00 2001 From: Containerman17 <8990432+containerman17@users.noreply.github.com> Date: Thu, 16 Jan 2025 08:17:08 +0000 Subject: [PATCH 3/6] AvalancheGo --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index cfd9c90eba..d8a8967568 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,8 @@ There are two options when using the Avalanche-CLI: ## 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 both environment variables and standard AvalancheGo config files. From 1e9ba8e382e225268213f9d8334b4d8b100cdd0d Mon Sep 17 00:00:00 2001 From: containerman17 <8990432+containerman17@users.noreply.github.com> Date: Fri, 17 Jan 2025 14:02:47 +0900 Subject: [PATCH 4/6] Update README.md Co-authored-by: Quentin McGaw Signed-off-by: containerman17 <8990432+containerman17@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e701c03b6..4f09999315 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ The `subnet-evm` Docker image comes with AvalancheGo pre-installed, making it ea ### Configuration -You can configure the `subnet-evm` Docker container using both environment variables and standard AvalancheGo config files. +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. - **Config Files**: Configure as you would with the regular AvalancheGo binary using config files. Ensure `HOME` is set to `/home/avalanche` and mount the config directory with `-v ~/.avalanchego:/home/avalanche/.avalanchego`. From a728abff0d71c24ad9c0b8a0afb869deb484eea0 Mon Sep 17 00:00:00 2001 From: Containerman17 <8990432+containerman17@users.noreply.github.com> Date: Fri, 17 Jan 2025 05:09:56 +0000 Subject: [PATCH 5/6] set default AVAGO_PLUGIN_DIR --- Dockerfile | 1 + README.md | 3 --- 2 files changed, 1 insertion(+), 3 deletions(-) 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 5e701c03b6..320911aeba 100644 --- a/README.md +++ b/README.md @@ -141,14 +141,12 @@ mkdir -p ~/.avalanchego/staking; docker run -it -d \ -e AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK=true \ -e AVAGO_TRACK_SUBNETS=REPLACE_THIS_WITH_YOUR_SUBNET_ID \ -e AVAGO_PUBLIC_IP_RESOLUTION_SERVICE=ifconfigme \ - -e AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ \ -e HOME=/home/avalanche \ --user $(id -u):$(id -g) \ avaplatform/subnet-evm:v0.7.1 ``` - `AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK`: Ensures you don't sync the X and C-Chains. -- `AVAGO_PLUGIN_DIR`: Sets the directory for the `subnet-evm` plugin. - `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. @@ -168,7 +166,6 @@ mkdir -p ~/.avalanchego_rpc/staking; docker run -it -d \ -e AVAGO_HTTP_ALLOWED_HOSTS="*" \ -e AVAGO_HTTP_HOST=0.0.0.0 \ -e AVAGO_PUBLIC_IP_RESOLUTION_SERVICE=ifconfigme \ - -e AVAGO_PLUGIN_DIR=/avalanchego/build/plugins/ \ -e HOME=/home/avalanche \ --user $(id -u):$(id -g) \ avaplatform/subnet-evm:v0.7.1 From 835a9da3b9051de420c650c3072c90d23ccc4abc Mon Sep 17 00:00:00 2001 From: Containerman17 <8990432+containerman17@users.noreply.github.com> Date: Fri, 17 Jan 2025 05:27:46 +0000 Subject: [PATCH 6/6] addresses the feedback --- README.md | 30 ++++++++++++------------------ 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 34dab4713c..a0a0ba0383 100644 --- a/README.md +++ b/README.md @@ -107,16 +107,13 @@ The `subnet-evm` Docker image comes with AvalancheGo pre-installed, making it ea 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. -- **Config Files**: Configure as you would with the regular AvalancheGo binary using config files. Ensure `HOME` is set to `/home/avalanche` and mount the config directory with `-v ~/.avalanchego:/home/avalanche/.avalanchego`. +- **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 `.avalanchego` directory. - -- **Create Directory**: Run `mkdir -p ~/.avalanchego/staking` beforehand to create the necessary directories and avoid file system access issues. -- **Set Permissions**: Run the container with `--user $(id -u):$(id -g)` to ensure proper access rights. -- **Set Home and Mount**: Set `HOME` to `/home/avalanche` and mount the data directory with `-v ~/.avalanchego:/home/avalanche/.avalanchego`. +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 @@ -125,15 +122,16 @@ Run `docker stop avago; docker rm avago;` then start a new container with the la ### 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 -mkdir -p ~/.avalanchego/staking; docker run -it -d \ +docker run -it -d \ --name avago \ --network host \ -v ~/.avalanchego:/home/avalanche/.avalanchego \ @@ -141,9 +139,7 @@ mkdir -p ~/.avalanchego/staking; docker run -it -d \ -e AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK=true \ -e AVAGO_TRACK_SUBNETS=REPLACE_THIS_WITH_YOUR_SUBNET_ID \ -e AVAGO_PUBLIC_IP_RESOLUTION_SERVICE=ifconfigme \ - -e HOME=/home/avalanche \ - --user $(id -u):$(id -g) \ - avaplatform/subnet-evm:v0.7.1 + avaplatform/subnet-evm:v0.7.1-rc.0 ``` - `AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK`: Ensures you don't sync the X and C-Chains. @@ -154,24 +150,22 @@ mkdir -p ~/.avalanchego/staking; docker run -it -d \ #### Fuji Subnet RPC ```bash -mkdir -p ~/.avalanchego_rpc/staking; docker run -it -d \ +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=REPLACE_THIS_WITH_YOUR_SUBNET_ID \ + -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 \ - -e HOME=/home/avalanche \ - --user $(id -u):$(id -g) \ - avaplatform/subnet-evm:v0.7.1 + 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. +- `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.