add(Docker): Docs for mining with Docker

[upbqdn]

Motivation

Close #6611.

Depends-On: #7200 and #7231.

Solution

Reviewer Checklist

• Will the PR name make sense to users?
  • Does it need extra CHANGELOG info? (new features, breaking changes, large changes)
• Are the PR labels correct?
• Does the code do what the ticket and PR says?
  • Does it change concurrent code, unsafe code, or consensus rules?
• How do you know it works? Does it have tests?

Follow Up Work

#7008.

[upbqdn]

We'll need to test the commands in the docs when we do the next release. It would be good if we could test them before the release, but I don't know how.

[teor2345]

We'll need to test the commands in the docs when we do the next release. It would be good if we could test them before the release, but I don't know how.

You can test the commands on the release image in the CD builds, they use the runtime target:

zebra/.github/workflows/continous-delivery.yml

Line 114 in f6afec2

dockerfile_target: runtime

It seems like you'll want to test against us-docker.pkg.dev/zfnd-dev-zebra/zebra/zebrad:pr-7178, which is from:
https://github.com/ZcashFoundation/zebra/actions/runs/5501189414/jobs/10024596480?pr=7178#step:10:1985
(the CD build job on PR #7178).

But it doesn't use the getblocktemplate-rpcs feature, so I guess we could add a features list to the manual deployment and build arguments?

zebra/.github/workflows/continous-delivery.yml

Lines 16 to 22 in f6afec2

	on:
	workflow_dispatch:
	inputs:
	network:
	default: 'Mainnet'
	description: 'Network to deploy: Mainnet or Testnet'
	required: true

zebra/.github/workflows/continous-delivery.yml

Lines 109 to 115 in f6afec2

	build:
	name: Build CD Docker
	uses: ./.github/workflows/build-docker-image.yml
	with:
	dockerfile_path: ./docker/Dockerfile
	dockerfile_target: runtime
	image_name: zebrad

Or we could add a manual release trigger and tag it with the branch name. But that seems riskier, we could accidentally publish something that looks like a real release, and users would use it. (It might also update the latest tag and get used automatically by Docker.)

[gustavovalverde]

LGTM!

[teor2345]

Have these commands been tested against the Docker image changes yet?

You can build Docker images locally if that helps?

[gustavovalverde]

I tested this locally, as a result of executing the commands in this PR I got these configurations:

Running docker run -e MINER_ADDRESS="t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v" -p 18232:18232 zfnd/<local_rpc_image>

Creates this zebrad.toml:

[network]
network = "Testnet"
listen_addr = "0.0.0.0"
[state]
cache_dir = "/var/cache/zebrad-cache"
[tracing]
use_color = false
[mining]
miner_address = "t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v"

Running docker run -e NETWORK="Mainnet" -e RPC_PORT="8232" -e MINER_ADDRESS="t1XhG6pT9xRqRQn3BHP7heUou1RuYrbcrCc" -p 8232:8232 zfnd/zebra:<local_rpc_image>

Creates this zebrad.toml:

[network]
network = "Mainnet"
listen_addr = "0.0.0.0"
[state]
cache_dir = "/var/cache/zebrad-cache"
[rpc]
listen_addr = "0.0.0.0:8232"
[tracing]
use_color = false
[mining]
miner_address = "t1XhG6pT9xRqRQn3BHP7heUou1RuYrbcrCc"

[teor2345]

I tested this locally, as a result of executing the commands in this PR I got these configurations:

It looks like a RPC address is missing from this config, maybe it needs some parts of PR #7175? Or the getblocktemplate-rpcs feature?

[mpguerra]

Content looks good to me. I appreciate the clear examples.

I have not run any of the commands so I don't know whether they work or not which is why I'm not explicitly approving this PR.

[upbqdn]

I tested this locally, ...

I think testing the commands locally doesn't suffice. We need to test them against the images we publish.

It looks like a RPC address is missing from this config, maybe it needs some parts of PR #7175? Or the getblocktemplate-rpcs feature?

Yes, this is also true for the currently published images. #7175 attempts to fix it. I tried describing what the issue is and why the port doesn't propagate to Zebra's config in the PR description.

I don't see how we could leverage the getblocktemplate-rpcs for published images.

[upbqdn]

I set #7175 as a blocker for this PR. Let's figure out a proper config for the images, and then test this PR?

[mpguerra]

After speaking with Marek, these instructions won't work until we publish the next release so I'm blocking this on #7136

[gustavovalverde]

Minimum changes to get it in

[mpguerra]

Did we do the required tests to ensure that these instructions will work?

[gustavovalverde]

Did we do the required tests to ensure that these instructions will work?

@mpguerra With the required changes from my review, it's working.

[upbqdn]

Did we do the required tests to ensure that these instructions will work?

I didn't, and we ended up with images with Mainnet enabled by default which isn't what we intended. However, after thinking about it, I think this change is actually suitable because there will be no API change when we start officially supporting mining, and I don't really see how having Testnet enabled by default protects from wasting the miner's resources, which is the risk we wanted to avoid. The reason is that to waste resources, the miner has to use a significant mining power for an extended period of time, and by that time, they must know whether they're on Mainnet or Testnet.

[gustavovalverde]

The reason is that to waste resources, the miner has to use a significant mining power for an extended period of time, and by that time, they must know whether they're on Mainnet or Testnet.

@upbqdn when I tested this the first time I used this command, which defaults to Mainnet:

docker run -e MINER_ADDRESS="t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v" -p 18232:18232 zfnd/zebra:v1.1.0.experimental

And the application panicked with the following error:

The application panicked (crashed).
Message:  assertion failed: `(left == right)`
  left: `Testnet`,
 right: `Mainnet`: incorrect miner address config: t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v network.network Mainnet and miner address network Testnet must match
Location: /opt/zebrad/zebra-rpc/src/server.rs:158

From my perspective, I doubt the user will be able to use the wrong Network, but I might not be considering other use-cases.

[upbqdn]

From my perspective, I doubt the user will be able to use the wrong Network, but I might not be considering other use-cases.

The issue isn't related to using an incompatible address; Zebra will always catch that. Our concern was that since we didn't have the means to test some of the mining functionality on Mainnet, users might run into bugs when running the image on Mainnet out of the box. However, as you pointed out, the image won't even start out of the box. Users have to first provide an address, which is either for Mainnet or Testnet, so they have to implicitly pick the network anyway. It's just a bit less of a hassle to start on Mainnet now, which I think is good.

[gustavovalverde]

Tested and LGTM!

[upbqdn]

I refactored almost all of the docs.

[upbqdn]

The examples work for me as well.

The issues raised in the review were addressed.