Skip to content

Commit 4addbdc

Browse files
kroesekroese
committed
Add workflow
1 parent 19ca425 commit 4addbdc

9 files changed

Lines changed: 301 additions & 0 deletions

File tree

‎.dockerignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.dockerignore
2+
.github
3+
.gitignore
4+
.gitlab-ci.yml
5+
.gitmodules
6+
.vscode
7+
Dockerfile
8+
Dockerfile.archive
9+
compose.yml
10+
compose.yaml
11+
docker-compose.yml
12+
docker-compose.yaml
13+
renovate.json
14+
15+
*.md

‎.github/dependabot.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: cargo
4+
directory: /
5+
schedule:
6+
interval: monthly
7+
open-pull-requests-limit: 0
8+
- package-ecosystem: docker
9+
directory: /
10+
schedule:
11+
interval: weekly
12+
open-pull-requests-limit: 0
13+
- package-ecosystem: github-actions
14+
directory: /
15+
schedule:
16+
interval: weekly

‎.github/logo.png‎

38 KB
Loading

‎.github/readme.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
<h1 align="center">Bitcoin RPC Proxy<br />
2+
<div align="center">
3+
<a href="https://github.com/dobtc/btc-rpc-proxy"><img src="https://raw.githubusercontent.com/dobtc/btc-rpc-proxy/master/.github/logo.png" title="Logo" style="max-width:100%;" width="128" /></a>
4+
</div>
5+
<div align="center">
6+
7+
[![Build]][build_url]
8+
[![Version]][tag_url]
9+
[![Size]][tag_url]
10+
[![Package]][pkg_url]
11+
[![Pulls]][hub_url]
12+
13+
</div></h1>
14+
15+
Finer-grained permission management for bitcoind.
16+
17+
## Usage 🐳
18+
19+
Via Docker Compose:
20+
21+
```yaml
22+
services:
23+
rpc-proxy:
24+
container_name: rpc-proxy
25+
image: dobtc/btc-rpc-proxy
26+
ports:
27+
- 8331:8331
28+
volumes:
29+
- ./btc_rpc_proxy.toml:/etc/btc_rpc_proxy.toml
30+
restart: always
31+
```
32+
33+
Via Docker CLI:
34+
35+
```bash
36+
docker run -it --rm --name rpc-proxy -p 8331:8331 -v ${PWD:-.}/btc_rpc_proxy.toml:/etc/btc_rpc_proxy.toml dobtc/btc-rpc-proxy
37+
```
38+
39+
## About ℹ️
40+
41+
This is a proxy made specifically for `bitcoind` to allow finer-grained control of permissions. It enables you to specify several users and for each user the list of RPC calls they are allowed to make. When run against a prunded node, the proxy will perform on-demand block fetching and verification, enabling features of a non-pruned node while still using a pruned node.
42+
43+
### Fine-grained permission management
44+
45+
This is useful because `bitcoind` allows every application with password to make possibly harmful calls like stopping the daemon or spending from wallet (if enabled). If you have several applications, you can provide the less trusted ones a different password and permissions than the others using this project.
46+
47+
There's another interesting advantage: since this is written in Rust, it might serve as a filter for **some** malformed requests which might be exploits. But I don't recommend relying on it!
48+
49+
### On-demand block fetching
50+
51+
By connecting to your pruned Bitcoin node through Bitcoin Proxy, your node will now behave as though it is not pruned. If a user or application requires a block that is not retained by your pruned node, Bitcoin Proxy will dynamically fetch the block over the P2P network, then verify its hash against your node to ensure validity.
52+
53+
This means that you can run multiple services against your _pruned_ Bitcoin node — such as Lightning and BTCPay — without them fighting for control over the pruning. Both are happy because both believe they are dealing with an _unpruned_ node.
54+
55+
A tradeoff to the proxy is speed and bandwidth. Every time the proxy needs to fetch a block not retained by your pruned node, it must reach out over the P2P network, consuming both Internet bandwidth and time.
56+
57+
## Usage
58+
59+
For security and performance reasons this application is written in Rust. Thus, you need a recent Rust compiler to compile it.
60+
61+
You need to configure the proxy using config files. You can specify their paths using `--conf /path/to/file.toml` or `--conf-dir /path/to/config/dir`. **Make sure to set their permissions to `600` before you write the passwords to them!** If `--conf-dir` is used, all files in that directory will be loaded and merged. You can use `--conf` multiple times. This is useful to organize your configuration (e.g. put sensitive information into a separate file).
62+
63+
An example configuration file is provided in this repository, hopefuly it's understandable. After configuring, you only need to run the compiled binary (e.g. using `cargo run --release -- --conf btc_rpc_proxy.toml`)
64+
65+
A man page can be generated using [`cfg_me`](https://crates.io/crates/cfg_me) and `--help` option is provided.
66+
67+
### Systemd integration
68+
69+
Using socket activation enables you to delay the start of `btc-rpc-proxy` until it's actually needed or start it in parallel with its clients leading to faster boot times.
70+
71+
Systemd socket activation is configured using `bind_systemd_socket_name` option.
72+
Setting it to a valid socket name will cause `btc-rpc-proxy` to use systemd socket activation using the socket with the specified socket name.
73+
74+
This feature is only available for Linux and only if the `systemd` feature is enabled. (Enabled by default.)
75+
Disabling it can decrease compile time and binary size but please keep it enabled if you intend to distribute the binary so that the users can benefit from it.
76+
Especially in case of packaged software.
77+
78+
## Limitations
79+
80+
* It uses `serde_json`, which allocates during deserialization (`Value`). Expect a bit lower performance than without proxy.
81+
* Logging can't be configured yet.
82+
* No support for changing UID.
83+
* No support for Unix sockets.
84+
* Redirect instead of blocking might be a useful feaure, which is now lacking.
85+
86+
## Stars 🌟
87+
[![Stars](https://starchart.cc/dobtc/btc-rpc-proxy.svg?variant=adaptive)](https://starchart.cc/dobtc/btc-rpc-proxy)
88+
89+
[build_url]: https://github.com/dobtc/btc-rpc-proxy/
90+
[hub_url]: https://hub.docker.com/r/dobtc/btc-rpc-proxy/
91+
[tag_url]: https://hub.docker.com/r/dobtc/btc-rpc-proxy/tags
92+
[pkg_url]: https://github.com/dobtc/btc-rpc-proxy/pkgs/container/btc-rpc-proxy
93+
94+
[Build]: https://github.com/dobtc/btc-rpc-proxy/actions/workflows/build.yml/badge.svg
95+
[Size]: https://img.shields.io/docker/image-size/dobtc/btc-rpc-proxy/latest?color=066da5&label=size
96+
[Pulls]: https://img.shields.io/docker/pulls/dobtc/btc-rpc-proxy.svg?style=flat&label=pulls&logo=docker
97+
[Version]: https://img.shields.io/docker/v/dobtc/btc-rpc-proxy/latest?arch=amd64&sort=semver&color=066da5
98+
[Package]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fipitio.github.io%2Fbackage%2Fdobtc%2Fbtc-rpc-proxy%2Fbtc-rpc-proxy.json&query=%24.downloads&logo=github&style=flat&color=066da5&label=pulls

‎.github/renovate.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
3+
"extends": ["config:recommended", ":disableDependencyDashboard"],
4+
"forkProcessing": "enabled",
5+
"woodpecker": {
6+
"enabled": false
7+
},
8+
"cargo": {
9+
"enabled": false
10+
}
11+
}

‎.github/workflows/build.yml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
name: Build
2+
3+
on:
4+
workflow_dispatch:
5+
6+
concurrency:
7+
group: build
8+
cancel-in-progress: false
9+
10+
jobs:
11+
build:
12+
name: Build
13+
runs-on: ubuntu-latest
14+
permissions:
15+
actions: write
16+
packages: write
17+
contents: read
18+
steps:
19+
-
20+
name: Checkout
21+
uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
-
25+
name: Lint Dockerfile
26+
uses: hadolint/hadolint-action@v3.1.0
27+
with:
28+
dockerfile: Dockerfile.custom
29+
ignore: DL3007,DL3008,DL3059
30+
failure-threshold: warning
31+
-
32+
name: Docker metadata
33+
id: meta
34+
uses: docker/metadata-action@v5
35+
with:
36+
context: git
37+
images: |
38+
${{ secrets.DOCKERHUB_REPO }}
39+
ghcr.io/${{ github.repository }}
40+
tags: |
41+
type=raw,value=latest,priority=100
42+
type=raw,value=${{ vars.MAJOR }}.${{ vars.MINOR }}
43+
labels: |
44+
org.opencontainers.image.title=${{ vars.NAME }}
45+
env:
46+
DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
47+
-
48+
name: Set up Docker Buildx
49+
uses: docker/setup-buildx-action@v3
50+
-
51+
name: Login into Docker Hub
52+
uses: docker/login-action@v3
53+
with:
54+
username: ${{ secrets.DOCKERHUB_USERNAME }}
55+
password: ${{ secrets.DOCKERHUB_TOKEN }}
56+
-
57+
name: Login to GitHub Container Registry
58+
uses: docker/login-action@v3
59+
with:
60+
registry: ghcr.io
61+
username: ${{ github.actor }}
62+
password: ${{ secrets.GITHUB_TOKEN }}
63+
-
64+
name: Build Docker image
65+
uses: docker/build-push-action@v6
66+
with:
67+
context: .
68+
push: true
69+
provenance: false
70+
file: ./Dockerfile.custom
71+
platforms: linux/amd64, linux/arm64
72+
tags: ${{ steps.meta.outputs.tags }}
73+
labels: ${{ steps.meta.outputs.labels }}
74+
annotations: ${{ steps.meta.outputs.annotations }}
75+
build-args: |
76+
RUST_RELEASE_MODE=release
77+
CARGO_BUILD_FEATURES=default
78+
VERSION_ARG=${{ steps.meta.outputs.version }}
79+
-
80+
name: Create a release
81+
uses: action-pack/github-release@v2
82+
with:
83+
tag: "v${{ steps.meta.outputs.version }}"
84+
title: "v${{ steps.meta.outputs.version }}"
85+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
86+
-
87+
name: Increment version variable
88+
uses: action-pack/bump@v2
89+
with:
90+
token: ${{ secrets.REPO_ACCESS_TOKEN }}
91+
-
92+
name: Send mail
93+
uses: action-pack/send-mail@v1
94+
with:
95+
to: ${{secrets.MAILTO}}
96+
from: Github Actions <${{secrets.MAILTO}}>
97+
connection_url: ${{secrets.MAIL_CONNECTION}}
98+
subject: Build of ${{ github.event.repository.name }} v${{ steps.meta.outputs.version }} completed
99+
body: |
100+
The build job of ${{ github.event.repository.name }} v${{ steps.meta.outputs.version }} was completed successfully!
101+
102+
See https://github.com/${{ github.repository }}/actions for more information.

‎.github/workflows/hub.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Update
2+
on:
3+
push:
4+
branches:
5+
- master
6+
paths:
7+
- .github/readme.md
8+
- .github/workflows/hub.yml
9+
10+
jobs:
11+
dockerHubDescription:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
-
16+
name: Docker Hub Description
17+
uses: peter-evans/dockerhub-description@v4
18+
with:
19+
username: ${{ secrets.DOCKERHUB_USERNAME }}
20+
password: ${{ secrets.DOCKERHUB_TOKEN }}
21+
repository: ${{ secrets.DOCKERHUB_REPO }}
22+
short-description: ${{ github.event.repository.description }}
23+
readme-filepath: ./.github/readme.md

‎Dockerfile.custom‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Builder
2+
FROM rust:1.85 AS builder
3+
ARG VERSION_ARG="0.0"
4+
5+
WORKDIR /app
6+
COPY . /app
7+
8+
RUN cargo build --release
9+
10+
FROM debian:bookworm-slim
11+
12+
ARG DEBCONF_NOWARNINGS="yes"
13+
ARG DEBIAN_FRONTEND="noninteractive"
14+
ARG DEBCONF_NONINTERACTIVE_SEEN="true"
15+
16+
RUN apt-get update && \
17+
apt-get --no-install-recommends -y install tini && \
18+
apt-get clean && \
19+
rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
20+
21+
COPY --chmod=600 --from=builder /app/btc_rpc_proxy.toml /etc/btc_rpc_proxy.toml
22+
COPY --chmod=755 --from=builder /app/target/release/btc_rpc_proxy /usr/local/bin/btc-rpc-proxy
23+
24+
EXPOSE 8331
25+
26+
ENTRYPOINT [ "tini", "--"]
27+
CMD ["/usr/local/bin/btc-rpc-proxy", "--conf", "/etc/btc_rpc_proxy.toml"]

‎compose.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
services:
2+
rpc-proxy:
3+
container_name: rpc-proxy
4+
image: dobtc/btc-rpc-proxy
5+
ports:
6+
- 8331:8331
7+
volumes:
8+
- ./btc_rpc_proxy.toml:/etc/btc_rpc_proxy.toml
9+
restart: always

0 commit comments

Comments
 (0)