chore: add Docker Usage Instructions to README.md #1424

containerman17 · 2025-01-16T04:33:31Z

Why this should be merged

The README.md currently lacks instructions on running subnet-evm using Docker. Adding a Docker section will help users set up and configure subnet-evm easily in containerized environments.

How this works

Added a new Run in Docker section to the README.md with brief instructions on configuration, data persistence, updating, networking, and example setups for both a Fuji subnet validator and RPC server.

How this was tested

I tested the examples manually.

Need to be documented?

No additional documentation is needed; all information is included in the updated README.md.

Need to update RELEASES.md?

No update to RELEASES.md is necessary since this is a documentation addition.

martineckardt · 2025-01-16T08:04:58Z

LGTM

qdm12

Nice! 💯

Just a few questions/comments to try to make this as simple as possible!

README.md

darioush · 2025-01-16T17:45:16Z

README.md

+
+### Updating
+
+Run `docker stop avago; docker rm avago;` then start a new container with the latest version tag in your `docker run` command.


nit (or maybe && is more appropriate)

Suggested change

Run `docker stop avago; docker rm avago;` then start a new container with the latest version tag in your `docker run` command.

Run `docker stop avago; docker rm avago` then start a new container with the latest version tag in your `docker run` command.

I would keep ; for idempotency. It doesn’t make an actual difference since docker stop always returns zero, but ; makes a clear statement: "all commands will execute no matter what."

I agree to remove the trailing ; I'm not sure why it's there.
For the middle ;, anyway docker rm avago will fail if the stop failed.

README.md

darioush · 2025-01-16T17:48:22Z

README.md

+- `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.


curious is it common / recommended to run both on the same machine?

I don’t see why not. It’s a trusted binary, so Docker-level isolation should be enough, as long as you have sufficient resources. Subnet-EVM without X and C chains doesn’t require much. Would I run it on the same machine for DFK? Probably not. But for 95% of other networks, especially on Fuji, I don’t see an issue.

Actually, that raises another question—why is it not recommended to run the same node as both a validator and a public RPC node?

It's not recommended as the validator could be targeted with many API requests when it is its turn to propose a block, or otherwise targeted so it can miss participating in necessary consensus queries.

Co-authored-by: Quentin McGaw <[email protected]> Signed-off-by: containerman17 <[email protected]>

darioush · 2025-01-21T22:57:56Z

README.md

+  -v ~/.avalanchego_rpc/:/home/avalanche/.avalanchego \
+  -e AVAGO_NETWORK_ID=fuji \
+  -e AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK=true \
+  -e AVAGO_TRACK_SUBNETS=hk755meusfKqBb9C9RfzzCxZFkdSXhaFHTcbtycMUSQ11o2cd \


should this be?

Suggested change

-e AVAGO_TRACK_SUBNETS=hk755meusfKqBb9C9RfzzCxZFkdSXhaFHTcbtycMUSQ11o2cd \

-e AVAGO_TRACK_SUBNETS=REPLACE_THIS_WITH_YOUR_SUBNET_ID \

qdm12 · 2025-01-24T10:03:27Z

README.md

+### 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`.


Suggested change

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`.

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`). Only port map the `AVAGO_STAKING_PORT` to the same port number, on both the container (e.g. `-p 1234:1234`) and your router port forwarding, otherwise it won't be reachable, which is explained below.

qdm12 · 2025-01-24T10:10:19Z

README.md

+- `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.


nit A markdown table with env variable, default value and description would be nice

qdm12 · 2025-01-24T10:18:02Z

README.md

+```
+
+- `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.


I would leave AVAGO_HTTP_PORT=9650 in the docker run command, and specify that the port can be changed in case of a conflict.

qdm12 · 2025-01-24T10:18:34Z

README.md

+  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`.


I would leave AVAGO_STAKING_PORT=9651 in the docker run command, and specify that the port can be changed in case of a conflict.

qdm12 · 2025-01-24T10:19:25Z

README.md

+
+```bash
+docker run -it -d \
+  --name rpc \


A more explicit name would be nice, for example

Suggested change

--name rpc \

--name avago-fuji-rpc \

qdm12 · 2025-01-24T10:20:35Z

README.md

+
+```bash
+docker run -it -d \
+  --name avago \


Suggested change

--name avago \

--name avago-fuji-validator \

qdm12 · 2025-01-24T10:21:45Z

README.md

+docker run -it -d \
+  --name avago \
+  --network host \
+  -v ~/.avalanchego:/home/avalanche/.avalanchego \


I would rather have it as

Suggested change

-v ~/.avalanchego:/home/avalanche/.avalanchego \

-v /your/validator/path:/home/avalanche/.avalanchego \

to make it explicit it can be chosen. Plus ~ doesn't work on Windows, if that matters.

qdm12 · 2025-01-24T10:22:29Z

README.md

+docker run -it -d \
+  --name rpc \
+  --network host \
+  -v ~/.avalanchego_rpc/:/home/avalanche/.avalanchego \


It would be nicer/clearer to just make it explicit the user should pick a path of their choosing

Suggested change

-v ~/.avalanchego_rpc/:/home/avalanche/.avalanchego \

-v /your/rpc/path/:/home/avalanche/.avalanchego \

qdm12 · 2025-01-24T10:23:38Z

README.md

+
+### Updating
+
+Run `docker stop avago; docker rm avago;` then start a new container with the latest version tag in your `docker run` command.


I agree to remove the trailing ; I'm not sure why it's there.
For the middle ;, anyway docker rm avago will fail if the stop failed.

qdm12 · 2025-01-24T10:26:16Z

README.md

+
+### 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.


I'm confused, the commands below bind mount /home/avalanche/.avalanchego although they don't have a user setting. Does it run as root or not by default??

docker readme

eadcde3

containerman17 requested review from ceyonur, darioush and a team as code owners January 16, 2025 04:33

fix Fuji Subnet RPC example

ec42aa7

containerman17 changed the title ~~Add Docker Usage Instructions to README.md~~ chore: add Docker Usage Instructions to README.md Jan 16, 2025

AvalancheGo

d4077ea

qdm12 reviewed Jan 16, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

ceyonur reviewed Jan 16, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

darioush reviewed Jan 16, 2025

View reviewed changes

containerman17 and others added 5 commits January 17, 2025 13:04

Merge branch 'ava-labs:master' into master

717d416

Update README.md

1e9ba8e

Co-authored-by: Quentin McGaw <[email protected]> Signed-off-by: containerman17 <[email protected]>

set default AVAGO_PLUGIN_DIR

a728abf

Merge branch 'master' of https://github.com/containerman17/subnet-evm

6d33427

addresses the feedback

835a9da

darioush reviewed Jan 21, 2025

View reviewed changes

qdm12 reviewed Jan 24, 2025

View reviewed changes

qdm12 requested changes Jan 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: add Docker Usage Instructions to README.md #1424

chore: add Docker Usage Instructions to README.md #1424

containerman17 commented Jan 16, 2025

martineckardt commented Jan 16, 2025

qdm12 left a comment •

edited

Loading

darioush Jan 16, 2025

containerman17 Jan 17, 2025

qdm12 Jan 24, 2025

darioush Jan 16, 2025

containerman17 Jan 17, 2025

darioush Jan 21, 2025

darioush Jan 21, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025

qdm12 Jan 24, 2025


		### Updating

		Run `docker stop avago; docker rm avago;` then start a new container with the latest version tag in your `docker run` command.

	Run `docker stop avago; docker rm avago;` then start a new container with the latest version tag in your `docker run` command.
	Run `docker stop avago; docker rm avago` then start a new container with the latest version tag in your `docker run` command.

	-e AVAGO_TRACK_SUBNETS=hk755meusfKqBb9C9RfzzCxZFkdSXhaFHTcbtycMUSQ11o2cd \
	-e AVAGO_TRACK_SUBNETS=REPLACE_THIS_WITH_YOUR_SUBNET_ID \

	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`.
	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`). Only port map the `AVAGO_STAKING_PORT` to the same port number, on both the container (e.g. `-p 1234:1234`) and your router port forwarding, otherwise it won't be reachable, which is explained below.

	-v ~/.avalanchego:/home/avalanche/.avalanchego \
	-v /your/validator/path:/home/avalanche/.avalanchego \

	-v ~/.avalanchego_rpc/:/home/avalanche/.avalanchego \
	-v /your/rpc/path/:/home/avalanche/.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.

chore: add Docker Usage Instructions to README.md #1424

Are you sure you want to change the base?

chore: add Docker Usage Instructions to README.md #1424

Conversation

containerman17 commented Jan 16, 2025

Why this should be merged

How this works

How this was tested

Need to be documented?

Need to update RELEASES.md?

martineckardt commented Jan 16, 2025

qdm12 left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qdm12 left a comment •

edited

Loading