Skip to content

docs: explain what Snowflake is and how the Dappnode package works #3

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

Merged
Pol-Lanski merged 3 commits into from
Mar 20, 2026
Merged

docs: explain what Snowflake is and how the Dappnode package works #3

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7fd941a
Initial plan
Copilot Mar 20, 2026
e24dca2
docs: rewrite README to explain Snowflake and how the Dappnode packag…
Copilot Mar 20, 2026
3dd8ecc
Update README with NAT info and remove publishing details
Pol-Lanski Mar 20, 2026
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
63 changes: 46 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,61 @@
# Snowflake Dappnode Package

This repository contains a minimal Dappnode package for running a Tor Snowflake proxy from the official upstream image.
Run a [Tor Snowflake](https://snowflake.torproject.org/) proxy on your Dappnode and help censored users around the world access the internet freely.

## Publishing
## What is Snowflake?

This repo includes a GitHub Actions workflow at `.github/workflows/publish.yml` that publishes through the SDK flow and creates a GitHub release containing the `sdk-publish` link for the DAppNode publish site.
[Snowflake](https://snowflake.torproject.org/) is a **pluggable transport** developed by the [Tor Project](https://www.torproject.org/). It helps people living under censorship connect to the Tor network by disguising their traffic as ordinary video-call (WebRTC) traffic.

You can trigger it in either of these ways:
When you run a Snowflake proxy, your node acts as a temporary bridge: censored users connect through your proxy to reach the Tor network, while you never see or log the content of their traffic. The connection is end-to-end encrypted by Tor itself.

- Run the `Publish` workflow manually from the GitHub Actions tab and choose `patch`, `minor`, or `major`
- Push a temporary tag named `release`, `release/patch`, `release/minor`, or `release/major`
Key facts:

The workflow will:
- **You are a proxy, not an exit node.** Traffic that passes through your proxy is Tor-encrypted and exits the Tor network elsewhere. You do not relay raw internet traffic.
- **Low resource usage.** A Snowflake proxy typically uses only a small amount of bandwidth and CPU.
- **No configuration required.** Once installed and running, the proxy automatically registers itself with the Tor broker and starts serving users.

- Build the package for the declared architectures
- Upload the release to remote DAppNode IPFS infrastructure
- Create a prerelease on GitHub with release assets and a publish link to `https://dappnode.github.io/sdk-publish/`
- Create the final version tag automatically
More background: [Tor Project – Snowflake](https://community.torproject.org/relay/setup/snowflake/standalone/)

If this package has never been published before, add a repository secret named `DEVELOPER_ADDRESS` with the Ethereum address that should own the package repository. `GITHUB_TOKEN` is provided automatically by GitHub Actions.
## How the Dappnode Package Works

## Services
This package wraps the official upstream Snowflake standalone proxy image so it can be installed and managed through the Dappnode interface.

- `snowflake-proxy`: Standalone Snowflake proxy exposing a fixed UDP port range
### Installation

Install the package from the Dappnode DAppStore or by using the direct IPFS / ENS link. No manual Docker setup is needed.

### Services

| Service | Description |
|---|---|
| `snowflake-proxy` | Standalone Snowflake proxy. Registers with the Tor broker over HTTPS and accepts WebRTC peer connections from censored users. |

### Networking

Because Dappnode does not support `network_mode: host`, this package exposes a fixed UDP port range (`30000–30999`) mapped 1-to-1 to the host.

You might get classified as a **restricted NAT** by the broker. It still works! Just works less effectively. If you want to make sure you are receiving connections, use the flag `--verbose` in EXTRA_OPTS in the configuration tab.

If you want to improve the reachability further, you should:

1. Ensure your router forwards UDP ports **30000–30999** to your Dappnode host.
2. Ensure your host firewall (if any) allows inbound traffic on the same range.

### Configuration

The package exposes one environment variable that can be set in the Dappnode Package Config UI:

| Variable | Default | Description |
|---|---|---|
| `EXTRA_OPTS` | *(empty)* | Optional extra CLI flags passed directly to the `snowflake-proxy` binary. For example, set `--verbose` to enable verbose logging when troubleshooting. |

All available flags are documented in the [upstream repository](https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/-/tree/main/proxy).

### Logs

You can view the proxy logs in the Dappnode UI under **Packages → Snowflake → Logs**. With the default settings you will see periodic connection counts reported by the proxy. Add `--verbose` via `EXTRA_OPTS` for more detailed output.

## Notes

- The original `watchtower` sidecar was removed because Dappnode already manages package updates.
- The proxy uses the upstream `latest` image tag. Pinning to a specific upstream release is safer for reproducible builds.
- Dappnode rejected `network_mode: host`, so this package exposes a fixed UDP range instead. That should run, but it may classify as a restricted NAT unless the host and router allow the mapped range.
- Users can add optional Snowflake proxy CLI flags through the `EXTRA_OPTS` environment variable in package config. For example, set `EXTRA_OPTS=--verbose` to enable verbose logs when troubleshooting.
- The proxy uses the upstream `latest` image tag.