Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
+73 −0
Open

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

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
eadcde3
docker readme
containerman17 Jan 16, 2025
ec42aa7
fix Fuji Subnet RPC example
containerman17 Jan 16, 2025
d4077ea
AvalancheGo
containerman17 Jan 16, 2025
717d416
Merge branch 'ava-labs:master' into master
containerman17 Jan 17, 2025
1e9ba8e
Update README.md
containerman17 Jan 17, 2025
a728abf
set default AVAGO_PLUGIN_DIR
containerman17 Jan 17, 2025
6d33427
Merge branch 'master' of https://github.com/containerman17/subnet-evm
containerman17 Jan 17, 2025
835a9da
addresses the feedback
containerman17 Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,3 +98,84 @@ 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 both environment variables and standard AvalancheGo config files.
containerman17 marked this conversation as resolved.
Show resolved Hide resolved

- **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`.
containerman17 marked this conversation as resolved.
Show resolved Hide resolved

### Data Persistence

To persist data across container restarts, you need to mount the `.avalanchego` directory.
containerman17 marked this conversation as resolved.
Show resolved Hide resolved

- **Create Directory**: Run `mkdir -p ~/.avalanchego/staking` beforehand to create the necessary directories and avoid file system access issues.
containerman17 marked this conversation as resolved.
Show resolved Hide resolved
- **Set Permissions**: Run the container with `--user $(id -u):$(id -g)` to ensure proper access rights.
containerman17 marked this conversation as resolved.
Show resolved Hide resolved
- **Set Home and Mount**: Set `HOME` to `/home/avalanche` and mount the data directory with `-v ~/.avalanchego:/home/avalanche/.avalanchego`.
containerman17 marked this conversation as resolved.
Show resolved Hide resolved
containerman17 marked this conversation as resolved.
Show resolved Hide resolved

### Updating

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### 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`.
qdm12 marked this conversation as resolved.
Show resolved Hide resolved

### Example Configs

#### Fuji Subnet Validator

```bash
mkdir -p ~/.avalanchego/staking; docker run -it -d \
--name avago \
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
--name avago \
--name avago-fuji-validator \

--network host \
-v ~/.avalanchego:/home/avalanche/.avalanchego \
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

-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
mkdir -p ~/.avalanchego_rpc/staking; docker run -it -d \
--name rpc \
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A more explicit name would be nice, for example

Suggested change
--name rpc \
--name avago-fuji-rpc \

--network host \
-v ~/.avalanchego_rpc/:/home/avalanche/.avalanchego \
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 \

-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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- `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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Loading