Skip to content

Commit

Permalink
docs(docker): update examples for running Zebra in Docker (#9269)
Browse files Browse the repository at this point in the history 
* Rm `.env` files

* Update `mining-docker.md`

* Revert "Rm `.env` files"

This reverts commit caaa455.

* Add `enable_cookie_auth` to default Zebra conf

* Rename `default_zebra_config.toml`

* fmt `prometheus.yaml`

* Update `docker/test.env`

* Update `docker/.env`

* Refactor `docker compose` for lwd

* Enable disabling cookie authentication

* Update `docker compose` for tests

* Update general `docker compose`

* Update docs for running Zebra in Docker

* Add example `docker compose` file for Grafana

* Fix a bug in an example command

* Refactor test execution logic in entrypoint

* Rename `v2.1.0.toml` conf to `custom-conf.toml`

* Fix CI tests for loading of custom conf files

* Use the new conf file name in CI checks

* Use an extended regexp for custom conf CI check
  • Loading branch information
@upbqdn
upbqdn authored Feb 19, 2025
1 parent 1e9f021 commit ac25192
Show file tree
Hide file tree
Showing 18 changed files with 483 additions and 401 deletions.
2 changes: 1 addition & 1 deletion .dockerignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@
!zebra-*
!zebrad
!docker/entrypoint.sh
!docker/default_zebra_config.toml
!docker/default-zebra-config.toml
4 changes: 2 additions & 2 deletions .github/workflows/cd-deploy-nodes-gcp.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,8 +168,8 @@ jobs:
with:
test_id: "custom-conf"
docker_image: ${{ vars.GAR_BASE }}/zebrad@${{ needs.build.outputs.image_digest }}
test_variables: '-e ZEBRA_CONF_PATH="zebrad/tests/common/configs/v2.1.0.toml"'
grep_patterns: '-e "loaded zebrad config.*config_path.*=.*v2.1.0.toml"'
test_variables: '-e ZEBRA_CONF_PATH="zebrad/tests/common/configs/custom-conf.toml"'
grep_patterns: '-e "extra_coinbase_data:\sSome\(\"do you even shield\?\"\)"'

# Each time this workflow is executed, a build will be triggered to create a new image
# with the corresponding tags using information from Git
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/sub-ci-unit-tests-docker.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -157,8 +157,8 @@ jobs:
with:
test_id: "custom-conf"
docker_image: ${{ vars.GAR_BASE }}/${{ vars.CI_IMAGE_NAME }}@${{ inputs.image_digest }}
grep_patterns: '-e "loaded zebrad config.*config_path.*=.*v2.1.0.toml"'
test_variables: '-e ZEBRA_CONF_PATH="zebrad/tests/common/configs/v2.1.0.toml"'
test_variables: '-e ZEBRA_CONF_PATH="zebrad/tests/common/configs/custom-conf.toml"'
grep_patterns: '-e "extra_coinbase_data:\sSome\(\"do you even shield\?\"\)"'

failure-issue:
name: Open or update issues for main branch failures
Expand Down
227 changes: 105 additions & 122 deletions book/src/user/docker.md
View file
Original file line number Diff line number Diff line change
@@ -1,176 +1,159 @@
# Zebra with Docker

The easiest way to run Zebra is using [Docker](https://docs.docker.com/get-docker/).
The foundation maintains a Docker infrastructure for deploying and testing Zebra.

We've embraced Docker in Zebra for most of the solution lifecycle, from development environments to CI (in our pipelines), and deployment to end users.
## Quick Start

> [!TIP]
> We recommend using `docker compose` sub-command over the plain `docker` CLI, especially for more advanced use-cases like running CI locally, as it provides a more convenient and powerful way to manage multi-container Docker applications. See [CI/CD Local Testing](#cicd-local-testing) for more information, and other compose files available in the [docker](https://github.com/ZcashFoundation/zebra/tree/main/docker) folder.
## Quick usage

You can deploy Zebra for daily use with the images available in [Docker Hub](https://hub.docker.com/r/zfnd/zebra) or build it locally for testing.

### Ready to use image

Using `docker compose`:
To get Zebra quickly up and running, you can use an off-the-rack image from
[Docker Hub](https://hub.docker.com/r/zfnd/zebra/tags):

```shell
docker compose -f docker/docker-compose.yml up
docker run --name zebra zfnd/zebra
```

With plain `docker` CLI:
If you want to preserve Zebra's state, you can create a Docker volume:

```shell
docker volume create zebrad-cache

docker run -d --platform linux/amd64 \
--restart unless-stopped \
--env-file .env \
--mount type=volume,source=zebrad-cache,target=/home/zebra/.cache/zebra \
-p 8233:8233 \
--memory 16G \
--cpus 4 \
zfnd/zebra
```

### Build it locally
And mount it before you start the container:

```shell
git clone --depth 1 --branch v2.2.0 https://github.com/ZcashFoundation/zebra.git
docker build --file docker/Dockerfile --target runtime --tag zebra:local .
docker run --detach zebra:local
```

### Alternatives

See [Building Zebra](https://github.com/ZcashFoundation/zebra#building-zebra) for more information.

## Advanced usage

You're able to specify various parameters when building or launching the Docker image, which are meant to be used by developers and CI pipelines. For example, specifying the Network where Zebra will run (Mainnet, Testnet, etc), or enabling features like metrics with Prometheus.

For example, if we'd like to enable metrics on the image, we'd build it using the following `build-arg`:

> [!IMPORTANT]
> To fully use and display the metrics, you'll need to run a Prometheus and Grafana server, and configure it to scrape and visualize the metrics endpoint. This is explained in more detailed in the [Metrics](https://zebra.zfnd.org/user/metrics.html#zebra-metrics) section of the User Guide.
```shell
docker build -f ./docker/Dockerfile --target runtime --build-arg FEATURES='default-release-binaries prometheus' --tag local/zebra.mining:latest .
docker run \
--mount type=volume,source=zebrad-cache,target=/home/zebra/.cache/zebra \
--name zebra \
zfnd/zebra
```

To increase the log output we can optionally add these `build-arg`s:
You can also use `docker compose`, which we recommend. First get the repo:

```shell
--build-arg RUST_BACKTRACE=full --build-arg RUST_LOG=debug --build-arg COLORBT_SHOW_HIDDEN=1
git clone --depth 1 --branch v2.2.0 https://github.com/ZcashFoundation/zebra.git
cd zebra
```

And after our image has been built, we can run it on `Mainnet` with the following command, which will expose the metrics endpoint on port `9999` and force the logs to be colored:
Then run:

```shell
docker run --env LOG_COLOR="true" -p 9999:9999 local/zebra.mining
```

Based on our actual `entrypoint.sh` script, the following configuration file will be generated (on the fly, at startup) and used by Zebra:

```toml
[network]
network = "Mainnet"
listen_addr = "0.0.0.0"
[state]
cache_dir = "/home/zebra/.cache/zebra"
[metrics]
endpoint_addr = "127.0.0.1:9999"
docker compose -f docker/docker-compose.yml up
```

### Running Zebra with Lightwalletd
## Custom Images

To run Zebra with Lightwalletd, we recommend using the provided `docker compose` files for Zebra and Lightwalletd, which will start both services and connect them together, while exposing ports, mounting volumes, and setting environment variables.
If you want to use your own images with, for example, some opt-in compilation
features enabled, add the desired features to the `FEATURES` variable in the
`docker/.env` file and build the image:

```shell
docker compose -f docker/docker-compose.yml -f docker/docker-compose.lwd.yml up
docker build \
--file docker/Dockerfile \
--env-file docker/.env \
--target runtime \
--tag zebra:local \
.
```

### CI/CD Local Testing

To run CI tests locally, which mimics the testing done in our CI pipelines on GitHub Actions, use the `docker-compose.test.yml` file. This setup allows for a consistent testing environment both locally and in CI.

#### Running Tests Locally

1. **Setting Environment Variables**:
- Modify the `test.env` file to set the desired test configurations.
- For running all tests, set `RUN_ALL_TESTS=1` in `test.env`.

2. **Starting the Test Environment**:
- Use Docker Compose to start the testing environment:

```shell
docker-compose -f docker/docker-compose.test.yml up
```

- This will start the Docker container and run the tests based on `test.env` settings.

3. **Viewing Test Output**:
- The test results and logs will be displayed in the terminal.
All available Cargo features are listed at
<https://docs.rs/zebrad/latest/zebrad/index.html#zebra-feature-flags>.

4. **Stopping the Environment**:
- Once testing is complete, stop the environment using:
## Configuring Zebra

```shell
docker-compose -f docker/docker-compose.test.yml down
```
To configure Zebra, edit the `docker/default-zebra-config.toml` config file and
uncomment the `configs` mapping in `docker/docker-compose.yml` so your config
takes effect. You can see if your config works as intended by looking at Zebra's
logs.

This approach ensures you can run the same tests locally that are run in CI, providing a robust way to validate changes before pushing to the repository.
Alternatively, you can configure Zebra by setting the environment variables in
the `docker/.env` file. Note that the config options of this file are limited to
the variables already present in the commented out blocks in it and adding new
ones will not be effective. Also note that the values of the variables take
precedence over the values set in the `docker/default-zebra-config.toml` config
file. The `docker/.env` file serves as a quick way to override the most commonly
used settings for Zebra, whereas the `docker/default-zebra-config.toml` file
provides full config capabilities.

### Build and Run Time Configuration
### RPC

#### Build Time Arguments
Zebra's RPC server is disabled by default. To enable it, you need to set its RPC
port. You can do that either in the `docker/default-zebra-config.toml` file or
`docker/.env` file, as described in the two paragraphs above.

#### Configuration
When connecting to Zebra's RPC server, your RPC clients need to provide an
authentication cookie to the server or you need to turn the authentication off
in Zebra's config. By default, the cookie file is stored at
`/home/zebra/.cache/zebra/.cookie` in the container. You can print its contents
by running

- `FEATURES`: Specifies the features to build `zebrad` with. Example: `"default-release-binaries getblocktemplate-rpcs"`

#### Logging
```bash
docker exec zebra cat /home/zebra/.cache/zebra/.cookie
```

- `RUST_LOG`: Sets the trace log level. Example: `"debug"`
- `RUST_BACKTRACE`: Enables or disables backtraces. Example: `"full"`
- `RUST_LIB_BACKTRACE`: Enables or disables library backtraces. Example: `1`
- `COLORBT_SHOW_HIDDEN`: Enables or disables showing hidden backtraces. Example: `1`
when the `zebra` container is running. Note that Zebra generates the cookie file
only if the RPC server is enabled, and each Zebra instance generates a unique
one. To turn the authentication off, either set `ENABLE_COOKIE_AUTH=false` in
`docker/.env` or set

#### Tests
```toml
[rpc]
enable_cookie_auth = false
```

- `ZEBRA_SKIP_IPV6_TESTS`: Skips IPv6 tests. Example: `1`
in `docker/default-zebra-config.toml` and mount this config file into the
container's filesystem in `docker/docker-compose.yml` as described at the
beginning of this section.

#### CI/CD
## Examples

- `SHORT_SHA`: Represents the short SHA of the commit. Example: `"a1b2c3d"`
To make the initial setup of Zebra with other services easier, we provide some
example files for `docker compose`. The following subsections will walk you
through those examples.

#### Run Time Variables
### Running Zebra with Lightwalletd

- `NETWORK`: Specifies the network type. Example: `"Mainnet"`
The following command will run Zebra with Lightwalletd:

#### Zebra Configuration
```shell
docker compose -f docker/docker-compose.lwd.yml up
```

- `ZEBRA_CACHE_DIR`: Directory for cached state. Example: `"/home/zebra/.cache/zebra"`
Note that Docker will run Zebra with the RPC server enabled and the cookie
authentication mechanism disabled since Lightwalletd doesn't support it. Instead
of configuring Zebra via the recommended config file or `docker/.env` file, we
configured the RPC server by setting environment variables directly in the
`docker/docker-compose.lwd.yml` file. This is a shortcut we can take when we are
familiar with the `docker/.env` file.

#### Mining Configuration
### Running Zebra with Prometheus and Grafana

- `RPC_LISTEN_ADDR`: Address for RPC to listen on. Example: `"0.0.0.0"`
- `MINER_ADDRESS`: Address for the miner. Example: `"t1XhG6pT9xRqRQn3BHP7heUou1RuYrbcrCc"`
The following commands will run Zebra with Prometheus and Grafana:

#### Other Configuration
```shell
docker compose -f docker/docker-compose.grafana.yml build --no-cache
docker compose -f docker/docker-compose.grafana.yml up
```

- `METRICS_ENDPOINT_ADDR`: Address for metrics endpoint. Example: `"0.0.0.0"`
- `METRICS_ENDPOINT_PORT`: Port for metrics endpoint. Example: `9999`
- `LOG_FILE`: Path to the log file. Example: `"/path/to/log/file.log"`
- `LOG_COLOR`: Enables or disables log color. Example: `false`
- `TRACING_ENDPOINT_ADDR`: Address for tracing endpoint. Example: `"0.0.0.0"`
- `TRACING_ENDPOINT_PORT`: Port for tracing endpoint. Example: `3000`
In this example, we build a local Zebra image with the `prometheus` Cargo
compilation feature. Note that we enable this feature by specifying its name in
the build arguments. Having this Cargo feature specified at build time makes
`cargo` compile Zebra with the metrics support for Prometheus enabled. Note that
we also specify this feature as an environment variable at run time. Having this
feature specified at run time makes Docker's entrypoint script configure Zebra
to open a scraping endpoint on `localhost:9999` for Prometheus.

Specific tests are defined in `docker/test.env` file and can be enabled by setting the corresponding environment variable to `1`.
Once all services are up, the Grafana web UI should be available at
`localhost:3000`, the Prometheus web UI should be at `localhost:9090`, and
Zebra's scraping page should be at `localhost:9999`. The default login and
password for Grafana are both `admin`. To make Grafana use Prometheus, you need
to add Prometheus as a data source with the URL `http://localhost:9090` in
Grafana's UI. You can then import various Grafana dashboards from the `grafana`
directory in the Zebra repo.

## Registries
### Running CI Tests Locally

The images built by the Zebra team are all publicly hosted. Old image versions meant to be used by our [CI pipeline](https://github.com/ZcashFoundation/zebra/blob/main/.github/workflows/ci-integration-tests-gcp.yml) (`zebrad-test`, `lightwalletd`) might be deleted on a scheduled basis.
To run CI tests locally, first set the variables in the `test.env` file to
configure the tests, then run:

We use [Docker Hub](https://hub.docker.com/r/zfnd/zebra) for end-user images and [Google Artifact Registry](https://console.cloud.google.com/artifacts/docker/zfnd-dev-zebra/us/zebra) to build external tools and test images.
```shell
docker-compose -f docker/docker-compose.test.yml up
```
47 changes: 34 additions & 13 deletions book/src/user/mining-docker.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,65 @@
# Mining with Zebra in Docker

Zebra's [Docker images](https://hub.docker.com/r/zfnd/zebra/tags) can be used for your mining
operations. If you don't have Docker, see the
[manual configuration instructions](https://zebra.zfnd.org/user/mining.html).
Zebra's [Docker images](https://hub.docker.com/r/zfnd/zebra/tags) can be used
for your mining operations. If you don't have Docker, see the [manual
configuration instructions](https://zebra.zfnd.org/user/mining.html).

Using docker, you can start mining by running:

```bash
docker run -e MINER_ADDRESS="t3dvVE3SQEi7kqNzwrfNePxZ1d4hUyztBA1" -p 8232:8232 zfnd/zebra:latest
docker run --name -zebra_local -e MINER_ADDRESS="t3dvVE3SQEi7kqNzwrfNePxZ1d4hUyztBA1" -e ZEBRA_RPC_PORT=8232 -p 8232:8232 zfnd/zebra:latest
```

This command starts a container on Mainnet and binds port 8232 on your Docker host. If you
want to start generating blocks, you need to let Zebra sync first.
This command starts a container on Mainnet and binds port 8232 on your Docker
host. If you want to start generating blocks, you need to let Zebra sync first.

Note that you must pass the address for your mining rewards via the
`MINER_ADDRESS` environment variable when you are starting the container, as we
did with the ZF funding stream address above. The address we used starts with the prefix `t1`,
meaning it is a Mainnet P2PKH address. Please remember to set your own address
for the rewards.
did with the ZF funding stream address above. The address we used starts with
the prefix `t1`, meaning it is a Mainnet P2PKH address. Please remember to set
your own address for the rewards.

The port we mapped between the container and the host with the `-p` flag in the
example above is Zebra's default Mainnet RPC port.

Instead of listing the environment variables on the command line, you can use
Docker's `--env-file` flag to specify a file containing the variables. You
can find more info here
Docker's `--env-file` flag to specify a file containing the variables. You can
find more info here
https://docs.docker.com/engine/reference/commandline/run/#env.

## Mining on Testnet
If you don't want to set any environment variables, you can edit the
`docker/default-zebra-config.toml` file, and pass it to Zebra before starting
the container. There's an example in `docker/docker-compose.yml` of how to do
that.

If you want to mine on Testnet, you need to set the `NETWORK` environment
variable to `Testnet` and use a Testnet address for the rewards. For example,
running

```bash
docker run -e NETWORK="Testnet" -e MINER_ADDRESS="t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v" -p 18232:18232 zfnd/zebra:latest
docker run --name zebra_local -e NETWORK="Testnet" -e MINER_ADDRESS="t27eWDgjFYJGVXmzrXeVjnb5J3uXDM9xH9v" -e ZEBRA_RPC_PORT=18232 -p 18232:18232 zfnd/zebra:latest
```

will start a container on Testnet and bind port 18232 on your Docker host, which
is the standard Testnet RPC port. Notice that we also used a different rewards
address. It starts with the prefix `t2`, indicating that it is a Testnet
address. A Mainnet address would prevent Zebra from starting on Testnet, and
conversely, a Testnet address would prevent Zebra from starting on Mainnet.

To connect to the RPC port, you will need the contents of the [cookie
file](https://zebra.zfnd.org/user/mining.html?highlight=cookie#testing-the-setup)
Zebra uses for authentication. By default, it is stored at
`/home/zebra/.cache/zebra/.cookie`. You can print its contents by running

```bash
docker exec -it zebra_local cat /home/zebra/.cache/zebra/.cookie
```

If you want to avoid authentication, you can turn it off by setting

```toml
[rpc]
enable_cookie_auth = false
```

in Zebra's config file before you start the container.
Loading

0 comments on commit ac25192

Please sign in to comment.