diff --git a/.github/workflows/build-docker.yml b/.github/workflows/build-docker.yml index 184ff8d..7084bd1 100644 --- a/.github/workflows/build-docker.yml +++ b/.github/workflows/build-docker.yml @@ -9,7 +9,7 @@ on: env: REGISTRY: ghcr.io - ORGANIZATION: 256-foundation + ORGANIZATION: 256foundation jobs: build: @@ -18,6 +18,7 @@ jobs: permissions: contents: read packages: write + id-token: write strategy: matrix: @@ -46,6 +47,9 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 + - name: Install Cosign + uses: sigstore/cosign-installer@v3 + - name: Login to GitHub Container Registry if: github.event_name != 'pull_request' uses: docker/login-action@v2 @@ -65,6 +69,7 @@ jobs: type=semver,pattern={{version}} type=semver,pattern={{major}}.{{minor}} type=sha + type=raw,value=latest,enable={{is_default_branch}} labels: | org.opencontainers.image.description=Hydrapool ${{ matrix.component }} image org.opencontainers.image.vendor=${{ env.ORGANIZATION }} @@ -72,6 +77,7 @@ jobs: org.opencontainers.image.visibility=public - name: Build and push + id: build uses: docker/build-push-action@v3 with: context: ${{ matrix.context }} @@ -81,3 +87,14 @@ jobs: labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max + + - name: Sign the images + if: github.event_name != 'pull_request' + run: | + images="${{ steps.meta.outputs.tags }}" + for tag in ${images}; do + echo "Signing ${tag}@${{ steps.build.outputs.digest }}" + cosign sign --yes "${tag}@${{ steps.build.outputs.digest }}" + done + env: + COSIGN_EXPERIMENTAL: 1 diff --git a/CHANGELOG.md b/CHANGELOG.md index de601a6..95e0ca1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.1.14] - 2025-10-31 + +### Added + +- Cosign docker images +- Add docker compose and config example to release +- Add docker compose instruction as primary way to run pool +- Support custom prometheus authentication + ### Deprecated - Ansible templates are not being maintained. We might bring them back in the future. - Enable running workflows from github tags page. +- Sign docker images with cosign ## [1.1.13] - 2025-10-30 @@ -45,8 +55,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add debian package workflow using cargo-deb -[unreleased]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.13...HEAD -[1.1.12]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.12...v1.1.13 +[unreleased]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.14...HEAD +[1.1.14]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.13...v1.1.4 +[1.1.13]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.12...v1.1.13 [1.1.12]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.11...v1.1.12 [1.1.11]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.10...v1.1.11 [1.1.10]: https://github.com/256-foundation/Hydra-Pool/compare/v1.1.9...v1.1.10 diff --git a/Cargo.lock b/Cargo.lock index e1a97f6..5ecff03 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1740,7 +1740,7 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" [[package]] name = "hydrapool" -version = "1.1.13" +version = "1.1.14" dependencies = [ "bitcoin", "bitcoindrpc", diff --git a/Cargo.toml b/Cargo.toml index 5a93f03..5a16d3c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "hydrapool" -version = "1.1.13" +version = "1.1.14" edition = "2024" rust-version = "1.88.0" authors = ["Kulpreet Singh"] @@ -67,4 +67,4 @@ assets = [ ] conf-files = ["/etc/hydrapool/config.toml"] maintainer-scripts = "packages/debian/" -systemd-units = { enable = false } \ No newline at end of file +systemd-units = { enable = false } diff --git a/README.md b/README.md index 7ab0c16..caeb884 100644 --- a/README.md +++ b/README.md @@ -33,83 +33,61 @@ limit on the size of the coinbase. # Running Your Own Hydrapool Instance -## Install Hydrapool - -```bash -curl --proto '=https' --tlsv1.2 -LsSf https://github.com/256-Foundation/Hydra-Pool/releases/latest/download/hydrapool-installer.sh | sh -``` - -The above will install two binaries in your path: - -1. `hydrapool` - the binary to start the pool. -2. `hydrapool_cli` - a utility to query the state of the pool, generate authentication tokens etc. - -Both binaries come with the `--help` option that document the other -options and commands they support. - -Binaries are available on the -[releases](https://github.com/256-Foundation/Hydra-Pool/releases) -page. We provide Linux, Windows and MacOS binaries. Go to releases -page to access an older release. - -## Start Hydrapool +## Run with Docker -Download the config file from -[config.toml](https://github.com/256-Foundation/Hydra-Pool/blob/main/config.toml) -and edit it for your addresses, donation and fee amounts as well as -your bitcoin RPC ports and credentials. Also consider securing your -server with new API Server credentials. See [Securing Your -Server](#secure). +We provide Dockerfile and docker compose files to run hydrapool using +Docker as well. -Once your config.toml file is ready, start the pool as: +### Download docker compose and pool config file -``` -hydrapool --config config.toml +```bash +curl --proto '=https' --tlsv1.2 -LsSf -o docker-compose.yml https://github.com/256foundation/hydrapool/releases/latest/download/docker-compose.yml +curl --proto '=https' --tlsv1.2 -LsSf -o config.toml https://github.com/256foundation/hydrapool/releases/latest/download/config-example.toml ``` -We recommend running a systemd service for a pool you want others to -access. A sample service is provided as -[hydrapool.service](hydrapool.service). +### Edit config.toml +Edit the file to provide details for your own bitcoin node. -### Start Dashboard +At the very least you will need to edit bitcoinrpc, zmqpubhashblock +and network (signet/main) to match your bitcoin node's settings. If +you use main network, change the bootstrap_address too. -Hydrapool ships with a prometheus/grafana dashboard to track the -hashrate of the pool and individual users and ASICs miners. - -The easiest way to run the dashboard is using docker. There is a -docker compose file for prometheus. - -``` -git clone https://github.com/256-foundation/Hydra-Pool/ -cd Hydra-Pool -cd docker -docker compose up -d +### Start pool +```bash +docker compose up -d docker-compose.yml ``` -The above will make a grafana dashboard available on -`localhost:3000`. You need to click on `dashboards` menu on the -left. There are two dashboards provided out of the box. `Pool` and -`Users and Hashrate`. +The above will start hydrapool stratum server on port 3333. A +monitoring dashboard on port 3000. If you are running on localhost, +`stratum://localhost:3333` and dashboard at +`http://localhost::3000`. + +# Dashboards -#### Pool Dashboard +## Pool Dashboard The `Pool` dashboard shows the hashrate of the pool, the shares per second, max difficulty reached by any of the workers. It also charts -the total number of users and workers in the pool over time. +the total number of users and workers in the pool over time and shows +the hashrate distribution between users mining on the pool. + +![Pool Dashboard Preview](./docs/images/pool_dashboard.png) -#### Users and Hashrate Dashboard +## Users and Hashrate Dashboard -This dashboard shows the stats for a selected user. For privacy, the -user needs to enter their bitcoin address used in their ASIC -configuration. There is a text input box at the top of the dashboard -where this btc address has to be entered. +Th users dashboard shows the stats for a selected user. The current +dashboard shows all users btcaddresses mining on the pool, and there +is a private dashboard where you have to provide the user's btcaddress +to view stats. By default the public dashboard is used. -Once the user has provided their btc address, they will be shown the -total hashrate of the all their workers as well as individual hashrate -for all their workers. They can also filter their workers by selecting -specific workers from the workers drop down on the top. +The dashboard shows the hashrate of the all their workers as well as +individual hashrate for all their workers. They can also filter their +workers by selecting specific workers from the workers drop down on +the top. -### Public Dashboard +![Users Dashboard Preview](./docs/images/users_dashboard.png) + +## Public Dashboard To provide public facing dashboard, we recommend using nginx/apache as a reverse proxy and running the dashboard as a system service. @@ -117,28 +95,30 @@ a reverse proxy and running the dashboard as a system service. Also see the section on securing the server for securing your API server. -## Config - -Before starting the pool, make sure you edit config.toml to point to -your bitcoin node. +# Verify Docker Image Signatures -You will also need to provide a bootstrap address. This address gets -the payout if in the extremely unlikely case the first few shares find -a bitcoin block. We build a new template every 10 seconds, so this -address can get lucky in the first 10 seconds. +To verify docker images [install +cosign](https://docs.sigstore.dev/cosign/system_config/installation/) +and then verify using: -We recommend pointing a single machine and warm up the pool for 10 -seconds before pointing more hashrate to the pool. +```bash +cosign verify \ + --certificate-identity-regexp=github.com/256foundation \ + ghcr.io/256-foundation/hydrapool: +``` -## Securing your Server +# Securing your Server -At the very least, change the API Server password in your -config.toml. We provide a command line tool to generate the salt and -hashed password to use in your config file. +If you provide public access to your api server, you can require +authentication to access the server. Edit the `auth_user` and +`auth_token` in config.toml. + +We provide a command line tool to generate the salt and hashed +password to use in your config file. ``` -hydrapool_cli gen-auth +docker compose run --rm hydrapool-cli gen-auth ``` The above will generate config lines for pasting into your @@ -148,17 +128,27 @@ Once the password is changed, you need to share that with your prometheus setup. The same credentials will also be used to access the API Server. -Edit the file prometheus/prometheus.yaml and change the username and -password as you output by hydrapool_cli above. +To update prometheus with your new credentials: +1. Copy the prometheus configuration template: +```bash +cp prometheus/prometheus.yml docker/prometheus.yml +``` +2. Edit `docker/prometheus.yml` and change the username and password to match what was output by hydrapool_cli above: ```yaml basic_auth: username: '' password: '' ``` +3. Restart the prometheus service: +```bash +docker compose restart prometheus +``` + +Note: By default, prometheus uses the built-in configuration with credentials `hydrapool/hydrapool`. Creating a custom `docker/prometheus.yml` file overrides this default configuration. -## API Server +# API Server When you start the mining pool an API server is also started on the port you specify in the config file. @@ -176,9 +166,6 @@ The above URL accepts optional query parameters `start_time` and `end_time` in RFC3339 format, e.g. `1996-12-19T16:39:57-08:00` to limit the range of pplns shares to download. -We will add new config options soon to rate limit the API Server for -easier administration of the server. - To expose the API Server to public, we recommend using nginx as a reverse proxy for the port, just like for the prometheus/grafana dashboard. @@ -201,22 +188,28 @@ Then run from target directory. ./target/release/hydrapool ``` -## Run with Docker - -We provide Dockerfile and docker compose files to run hydrapool using -Docker as well. +## Install Hydrapool Binaries ```bash -docker compose build hydrapool -docker compose --profile hydrapool up +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/256-Foundation/Hydra-Pool/releases/latest/download/hydrapool-installer.sh | sh ``` -Using the profile option we can start hydrapool along with prometheus -and grafana. +The above will install two binaries in your path: + +1. `hydrapool` - the binary to start the pool. +2. `hydrapool_cli` - a utility to query the state of the pool, generate authentication tokens etc. -If you don't provide the profile option, hydrapool won't be started -and only prometheus and grafana will start as normal. +Both binaries come with the `--help` option that document the other +options and commands they support. -When using docker, be careful that you need to build docker image -after changes to config. Also you need to make sure your bitcoin RPC -port is accessible from the docker container. +Binaries are available on the +[releases](https://github.com/256-Foundation/Hydra-Pool/releases) +page. We provide Linux, Windows and MacOS binaries. Go to releases +page to access an older release. + +To run dashboard, we still recommned using docker + +``` +docker compose up -d ghcr.io/256foundation/hydrapool-prometheus +docker compose up -d ghcr.io/256foundation/hydrapool-grafana +``` diff --git a/config.toml b/config.toml index f2310ba..bc16023 100644 --- a/config.toml +++ b/config.toml @@ -21,7 +21,7 @@ bootstrap_address = "bc1qypskemx80lznv4tjpnmpw9c5pgpy32fpkk3sw2" # fee = 200 zmqpubhashblock = "tcp://127.0.0.1:28334" # The network can be "main", "testnet4" or "signet" -network = "signet" +network = "main" version_mask = "1fffe000" # The difficulty multiplier defines the window size for calculating payout proportions # See https://github.com/p2poolv2/p2poolv2/wiki/Difficult-Multiplier on how to choose this diff --git a/dist-workspace.toml b/dist-workspace.toml index bb83e7c..74d0a73 100644 --- a/dist-workspace.toml +++ b/dist-workspace.toml @@ -15,3 +15,8 @@ targets = ["aarch64-apple-darwin", "aarch64-unknown-linux-gnu", "x86_64-apple-da install-path = "CARGO_HOME" # Whether to install an updater program install-updater = false + +[[dist.extra-artifacts]] +artifacts = ["docker/docker-compose.yml", "docker/config-example.yml"] +build = [""] + diff --git a/docker/Dockerfile.prometheus b/docker/Dockerfile.prometheus index fa5d55b..c39e34f 100644 --- a/docker/Dockerfile.prometheus +++ b/docker/Dockerfile.prometheus @@ -1,6 +1,16 @@ FROM prom/prometheus:v3.6.0 -# Copy custom prometheus configuration +# Copy default prometheus configuration COPY ./prometheus/prometheus.yml /etc/prometheus/prometheus.yml -# The base image already sets the correct entrypoint and command +# Copy and set up entrypoint script to support optional config override +COPY ./docker/prometheus-entrypoint.sh /usr/local/bin/prometheus-entrypoint.sh +RUN chmod +x /usr/local/bin/prometheus-entrypoint.sh + +# Override entrypoint to support custom config fallback +ENTRYPOINT ["/usr/local/bin/prometheus-entrypoint.sh"] + +# Default command arguments (can be overridden in docker-compose) +CMD ["--storage.tsdb.path=/prometheus", \ + "--web.console.libraries=/usr/share/prometheus/console_libraries", \ + "--web.console.templates=/usr/share/prometheus/consoles"] diff --git a/docker/README.md b/docker/README.md index e83d73d..bf6329f 100644 --- a/docker/README.md +++ b/docker/README.md @@ -59,6 +59,17 @@ After editing `config.toml`, restart Hydrapool: docker compose restart hydrapool ``` +## Updating to Latest Release + +To update to the latest released version: + +```bash +docker compose pull +docker compose up -d +``` + +This pulls the latest images from GitHub Container Registry and restarts services with the new versions. + ## Stopping Hydrapool ```bash @@ -99,13 +110,21 @@ docker run --rm -v hydrapool_data:/data -v $(pwd):/backup alpine tar czf /backup ## Building from Source -To rebuild the Docker image after code changes: +By default, `docker-compose.yml` uses pre-built images from GitHub Container Registry. + +For local development and testing changes: ```bash -docker compose build hydrapool -docker compose up -d hydrapool +# Build and run with local changes +docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build + +# Or rebuild specific service +docker compose -f docker-compose.yml -f docker-compose.dev.yml build hydrapool +docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d hydrapool ``` +The `docker-compose.dev.yml` file overrides the image references to build locally. + ## Troubleshooting ### Cannot connect to Bitcoin node diff --git a/docker/config-example.toml b/docker/config-example.toml index 2953f75..d6abd59 100644 --- a/docker/config-example.toml +++ b/docker/config-example.toml @@ -19,7 +19,7 @@ minimum_difficulty = 1 # # This address receives payouts if a block is found in the first 10 # seconds -bootstrap_address = "bc1qypskemx80lznv4tjpnmpw9c5pgpy32fpkk3sw2" +bootstrap_address = "tb1qyazxde6558qj6z3d9np5e6msmrspwpf6k0qggk" # Optional: Donation to developers (in basis points, 100 = 1%) # donation_address = "" diff --git a/docker/docker-compose.dev.yml b/docker/docker-compose.dev.yml new file mode 100644 index 0000000..424a4fd --- /dev/null +++ b/docker/docker-compose.dev.yml @@ -0,0 +1,27 @@ +# Docker Compose override for local development +# Usage: docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build + +services: + hydrapool: + build: + context: .. + dockerfile: docker/Dockerfile.hydrapool + image: hydrapool:dev + + hydrapool-cli: + build: + context: .. + dockerfile: docker/Dockerfile.hydrapool + image: hydrapool:dev + + prometheus: + build: + context: .. + dockerfile: docker/Dockerfile.prometheus + image: hydrapool-prometheus:dev + + grafana: + build: + context: .. + dockerfile: docker/Dockerfile.grafana + image: hydrapool-grafana:dev diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 014367b..8f5e806 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,8 +1,6 @@ services: hydrapool: - build: - context: .. - dockerfile: docker/Dockerfile.hydrapool + image: ghcr.io/256foundation/hydrapool:latest environment: - RUST_LOG=info # Config is mounted from local file - edit docker/config.toml to customize @@ -31,9 +29,7 @@ services: max-file: "3" hydrapool-cli: - build: - context: .. - dockerfile: docker/Dockerfile.hydrapool + image: ghcr.io/256foundation/hydrapool:latest profiles: [cli] # Prevents auto-start with docker compose up entrypoint: ["/usr/local/bin/hydrapool_cli", "--config", "/etc/hydrapool/config.toml"] volumes: @@ -43,18 +39,16 @@ services: - hydrapool_network prometheus: - build: - context: .. - dockerfile: docker/Dockerfile.prometheus + image: ghcr.io/256foundation/hydrapool-prometheus:latest depends_on: hydrapool: condition: service_healthy volumes: + - ./prometheus.yml:/etc/prometheus/prometheus.custom.yml:ro - prometheus_data:/prometheus ports: - "9090:9090" command: - - '--config.file=/etc/prometheus/prometheus.yml' - '--storage.tsdb.path=/prometheus' - '--web.console.libraries=/usr/share/prometheus/console_libraries' - '--web.console.templates=/usr/share/prometheus/consoles' @@ -74,9 +68,7 @@ services: max-file: "3" grafana: - build: - context: .. - dockerfile: docker/Dockerfile.grafana + image: ghcr.io/256foundation/hydrapool-grafana:latest depends_on: prometheus: condition: service_healthy diff --git a/docker/prometheus-entrypoint.sh b/docker/prometheus-entrypoint.sh new file mode 100644 index 0000000..83d157e --- /dev/null +++ b/docker/prometheus-entrypoint.sh @@ -0,0 +1,14 @@ +#!/bin/sh +set -e + +# Check if custom prometheus config exists, otherwise use default +if [ -f /etc/prometheus/prometheus.custom.yml ]; then + echo "Using custom prometheus configuration from prometheus.custom.yml" + CONFIG_FILE=/etc/prometheus/prometheus.custom.yml +else + echo "Using default prometheus configuration" + CONFIG_FILE=/etc/prometheus/prometheus.yml +fi + +# Start prometheus with the selected config +exec /bin/prometheus --config.file="$CONFIG_FILE" "$@" diff --git a/docs/images/pool_dashboard.png b/docs/images/pool_dashboard.png new file mode 100644 index 0000000..49cf60c Binary files /dev/null and b/docs/images/pool_dashboard.png differ diff --git a/docs/images/users_dashboard.png b/docs/images/users_dashboard.png new file mode 100644 index 0000000..6a537b8 Binary files /dev/null and b/docs/images/users_dashboard.png differ