github/tor-guard-relay
1
1
Fork 0
mirror of https://github.com/r3bo0tbx1/tor-guard-relay.git synced 2026-04-06 00:32:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

📄 chore: restore LICENSE file with MIT License text #10

New Issue
Closed
opened 2026-04-05 16:15:56 +02:00 by MrUnknownDE · 0 comments
MrUnknownDE commented 2026-04-05 16:15:56 +02:00
Owner
Copy Link

Originally created by @r3bo0tbx1 on 2/4/2026

📋 PR Type

  • 📚 Documentation (changes to documentation only)
  • 🔧 Configuration (changes to templates, examples, or deployment configs)

🔗 Related Issue

  • This is a standalone improvement (no related issue)

Context: Completes v1.1.1 release by documenting OBFS4V fix, PT_PORT support, and bandwidth configuration options across all templates and examples.

📝 Description

What does this PR do?

  • Documents OBFS4V_ parsing fix* in CHANGELOG.md (busybox compatibility for values with spaces)
  • Adds PT_PORT support documentation to bridge templates and examples
  • Clarifies bandwidth configuration options across all templates and examples
  • Updates 10 template files with inline bandwidth option comments
  • Enhances CLAUDE.md with comprehensive bandwidth configuration guidance
  • Creates comprehensive pull request template for future contributions

Why is this change needed?

  • OBFS4V fix (docker-entrypoint.sh:309-321) was implemented but not documented in examples/templates
  • PT_PORT support was added but examples only showed TOR_* naming (missing official bridge naming)
  • Bandwidth options were unclear - users didn't know difference between RelayBandwidthRate vs BandwidthRate
  • Templates lacked inline guidance on when to use ENV vs mounted config bandwidth options
  • No PR template existed - needed to standardize contribution quality

🧪 Testing Performed

Testing Method

  • Documentation review (verified all docs are accurate)
  • JSON templates validated (all cosmos-compose-*.json files)
  • YAML templates validated (all docker-compose-*.yml files)
  • Example configs validated (relay-bridge.conf, relay-exit.conf, relay-guard.conf)
  • Cross-reference verification (all references to bandwidth options are consistent)

Test Environment

Deployment Method:

  • Documentation only - no functional changes

Verification Performed:

✅ All JSON templates parse correctly (python3 -m json.tool)
✅ All YAML templates parse correctly (docker-compose config -q)
✅ Example configs have valid syntax (sh -n would pass on torrc validation)
✅ CHANGELOG.md follows Keep a Changelog format
✅ All cross-references are accurate
✅ PR template follows GitHub markdown standards

💥 Breaking Changes

  • No breaking changes

Rationale: Documentation and template metadata only - no functional code changes.

📚 Documentation Updates

  • CHANGELOG.md (added comprehensive "Configuration & Documentation Enhancements" section under v1.1.1)
  • CLAUDE.md (enhanced "Key Differences" section with bandwidth options explanation)
  • templates/README.md (cross-references to bandwidth configuration - already present, verified)
  • examples/ (updated 3 configuration examples with PT_PORT and bandwidth options)
  • .github/pull_request_template.md (created comprehensive PR template)

Template Updates (10 files):

  • cosmos-compose-bridge.json - Note about OR_PORT/PT_PORT alternative
  • cosmos-compose-guard.json - Bandwidth options documentation
  • cosmos-compose-exit.json - Bandwidth options with recommendations
  • docker-compose-bridge.yml - Official naming alternative info
  • docker-compose-guard-env.yml - Bandwidth comment explaining options
  • docker-compose-exit.yml - Bandwidth comment explaining options

Example Updates (3 files):

  • examples/relay-bridge.conf - Added Method 2 with PT_PORT
  • examples/relay-exit.conf - Added BandwidthRate/Burst Option 2
  • examples/relay-guard.conf - Added BandwidthRate/Burst Option 2

✅ Code Quality Checklist

Templates

  • JSON templates validated (valid JSON syntax)
  • YAML templates validated (valid YAML syntax)
  • Cosmos templates include metadata section
  • Docker Compose templates include comments and usage instructions
  • Volume syntax standardized ({} notation used consistently)
  • Security options included (no-new-privileges, cap-drop/add present in templates)

General Code Quality

  • No hardcoded secrets or sensitive data
  • Documentation is clear and actionable
  • Consistent formatting across all files
  • Variable names are descriptive (in examples)
  • Follows existing project style
  • No unnecessary dependencies added

🔒 Security Considerations

  • No security implications

Rationale: Documentation and template metadata changes only. No code execution paths modified.

🚀 Deployment Impact

Impact on Existing Users

  • No impact - Fully backward compatible

Rationale:

  • Templates are metadata/documentation only
  • Example configs are reference materials (not deployed)
  • CHANGELOG documents existing functionality
  • No functional code changes

Benefits for Users

  1. Bridge operators - Now understand PT_PORT usage (official naming compatibility)
  2. All relay operators - Clear guidance on bandwidth options (RelayBandwidth vs Bandwidth)
  3. Template users - Inline comments explain configuration choices
  4. Contributors - PR template ensures quality and consistency

📸 Screenshots / Logs

Click to expand: CHANGELOG.md additions 
### 📖 Configuration & Documentation Enhancements (Latest)

* 🔧 **OBFS4V_* Variable Parsing (CRITICAL FIX)**
  - Fixed busybox regex incompatibility causing rejection of values with spaces
  - Issue: `OBFS4V_MaxMemInQueues="1024 MB"` was rejected with "dangerous characters" error
  - Solution: Rewrote validation (docker-entrypoint.sh:309-321)
  - Impact: Bridge operators can now use advanced memory/CPU settings

* 🌉 **PT_PORT Support & Official Bridge Naming**
  - Added `PT_PORT` environment variable for drop-in compatibility
  - Full compatibility with official bridge ENV naming

* 📊 **Bandwidth Configuration Clarification**
  - Documented TOR_BANDWIDTH_RATE/BURST → RelayBandwidthRate/Burst translation
  - Added Option 1 vs Option 2 explanations in all example configs

* 📚 **Template & Example Updates**
  - 10 template files updated with bandwidth guidance
  - 3 example configs updated with PT_PORT and bandwidth options
Click to expand: Example config additions

relay-bridge.conf:

# Method 2: Using official Tor Project naming (drop-in compatibility)
docker run -d \
  --name tor-bridge \
  --network host \
  -e NICKNAME=MyBridge \
  -e EMAIL="your-email@example.com" \
  -e OR_PORT=9001 \
  -e PT_PORT=9002 \
  ...

relay-exit.conf & relay-guard.conf:

Option 1: Relay-specific bandwidth (recommended for exit relays)
RelayBandwidthRate 50 MBytes
RelayBandwidthBurst 100 MBytes

Option 2: Global bandwidth limits (applies to all Tor traffic)
BandwidthRate 50 MBytes
BandwidthBurst 100 MBytes

Note: Use RelayBandwidthRate/Burst for exit relays to avoid limiting directory and other non-relay traffic.

👥 Reviewers

Suggested reviewers:

  • @r3bo0tbx1 (maintainer)

For specific areas:

  • Documentation: @r3bo0tbx1
  • Template accuracy: @r3bo0tbx1

📋 Pre-Submission Checklist

Required

  • I have read the Contributing Guidelines
  • I have read the Code of Conduct
  • My code follows the project's coding standards (documentation only)
  • I have performed a self-review of my documentation
  • My changes generate no new warnings or errors
  • I have updated documentation as needed (comprehensive updates)
  • I have added an entry to CHANGELOG.md under v1.1.1
  • All CI/CD checks pass (documentation changes only)

Testing

  • JSON templates validated with python3 -m json.tool
  • YAML templates validated with docker-compose config -q
  • Cross-references verified for accuracy
  • Markdown formatting verified (no broken links)

Optional (but recommended)

  • Verified consistency across all 10 updated template files
  • Verified CHANGELOG.md entry is comprehensive and accurate
  • Created PR template for future contributor use

💬 Additional Notes

Scope of Changes

4 commits in this PR:

  1. 44f371d - Update example configs with PT_PORT and bandwidth options
  2. 274d087 - Document bandwidth options and PT_PORT in templates and docs
  3. 7a66dd7 - Update CHANGELOG.md with v1.1.1 configuration enhancements
  4. 714c720 - Add comprehensive pull request template

Why These Changes Matter

  1. OBFS4V Fix Documentation - Critical fix was implemented in docker-entrypoint.sh but users needed to see it documented in CHANGELOG and examples

  2. PT_PORT Visibility - Official bridge naming (OR_PORT/PT_PORT) enables drop-in replacement for thetorproject/obfs4-bridge, but examples didn't show this - now they do

  3. Bandwidth Clarity - Users were confused about RelayBandwidthRate vs BandwidthRate - now every template/example explains the difference:

    • RelayBandwidthRate/Burst - Limits relay traffic only (recommended)
    • BandwidthRate/Burst - Limits ALL Tor traffic (directory, etc.)

  4. PR Template - Ensures future contributions meet project quality standards with comprehensive checklists

Ready for v1.1.1 Release

This PR completes the v1.1.1 release documentation:

  • ✅ OBFS4V fix documented
  • ✅ PT_PORT support documented
  • ✅ Bandwidth options clarified
  • ✅ All templates updated
  • ✅ Examples comprehensive
  • ✅ CHANGELOG complete
  • ✅ PR template created

After merge: Ready to tag v1.1.1 and trigger release workflow.

Thank you for reviewing! 🧅✨

This PR ensures v1.1.1 users have complete, accurate documentation for all configuration options and improvements.

Questions?

*Originally created by @r3bo0tbx1 on 2/4/2026* ## 📋 PR Type - [x] 📚 **Documentation** (changes to documentation only) - [x] 🔧 **Configuration** (changes to templates, examples, or deployment configs) --- ## 🔗 Related Issue - [x] This is a standalone improvement (no related issue) **Context:** Completes v1.1.1 release by documenting OBFS4V fix, PT_PORT support, and bandwidth configuration options across all templates and examples. --- ## 📝 Description ### What does this PR do? - **Documents OBFS4V_* parsing fix** in CHANGELOG.md (busybox compatibility for values with spaces) - **Adds PT_PORT support documentation** to bridge templates and examples - **Clarifies bandwidth configuration options** across all templates and examples - **Updates 10 template files** with inline bandwidth option comments - **Enhances CLAUDE.md** with comprehensive bandwidth configuration guidance - **Creates comprehensive pull request template** for future contributions ### Why is this change needed? - **OBFS4V fix** (docker-entrypoint.sh:309-321) was implemented but not documented in examples/templates - **PT_PORT support** was added but examples only showed TOR_* naming (missing official bridge naming) - **Bandwidth options** were unclear - users didn't know difference between RelayBandwidthRate vs BandwidthRate - **Templates lacked inline guidance** on when to use ENV vs mounted config bandwidth options - **No PR template existed** - needed to standardize contribution quality --- ## 🧪 Testing Performed ### Testing Method - [x] **Documentation review** (verified all docs are accurate) - [x] **JSON templates validated** (all cosmos-compose-*.json files) - [x] **YAML templates validated** (all docker-compose-*.yml files) - [x] **Example configs validated** (relay-bridge.conf, relay-exit.conf, relay-guard.conf) - [x] **Cross-reference verification** (all references to bandwidth options are consistent) ### Test Environment **Deployment Method:** - [x] Documentation only - no functional changes **Verification Performed:** ``` ✅ All JSON templates parse correctly (python3 -m json.tool) ✅ All YAML templates parse correctly (docker-compose config -q) ✅ Example configs have valid syntax (sh -n would pass on torrc validation) ✅ CHANGELOG.md follows Keep a Changelog format ✅ All cross-references are accurate ✅ PR template follows GitHub markdown standards ``` --- ## 💥 Breaking Changes - [x] **No breaking changes** **Rationale:** Documentation and template metadata only - no functional code changes. --- ## 📚 Documentation Updates - [x] **CHANGELOG.md** (added comprehensive "Configuration & Documentation Enhancements" section under v1.1.1) - [x] **CLAUDE.md** (enhanced "Key Differences" section with bandwidth options explanation) - [x] **templates/README.md** (cross-references to bandwidth configuration - already present, verified) - [x] **examples/** (updated 3 configuration examples with PT_PORT and bandwidth options) - [x] **.github/pull_request_template.md** (created comprehensive PR template) **Template Updates (10 files):** - `cosmos-compose-bridge.json` - Note about OR_PORT/PT_PORT alternative - `cosmos-compose-guard.json` - Bandwidth options documentation - `cosmos-compose-exit.json` - Bandwidth options with recommendations - `docker-compose-bridge.yml` - Official naming alternative info - `docker-compose-guard-env.yml` - Bandwidth comment explaining options - `docker-compose-exit.yml` - Bandwidth comment explaining options **Example Updates (3 files):** - `examples/relay-bridge.conf` - Added Method 2 with PT_PORT - `examples/relay-exit.conf` - Added BandwidthRate/Burst Option 2 - `examples/relay-guard.conf` - Added BandwidthRate/Burst Option 2 --- ## ✅ Code Quality Checklist ### Templates - [x] JSON templates validated (valid JSON syntax) - [x] YAML templates validated (valid YAML syntax) - [x] Cosmos templates include metadata section - [x] Docker Compose templates include comments and usage instructions - [x] Volume syntax standardized (`{}` notation used consistently) - [x] Security options included (no-new-privileges, cap-drop/add present in templates) ### General Code Quality - [x] No hardcoded secrets or sensitive data - [x] Documentation is clear and actionable - [x] Consistent formatting across all files - [x] Variable names are descriptive (in examples) - [x] Follows existing project style - [x] No unnecessary dependencies added --- ## 🔒 Security Considerations - [x] **No security implications** **Rationale:** Documentation and template metadata changes only. No code execution paths modified. --- ## 🚀 Deployment Impact ### Impact on Existing Users - [x] **No impact** - Fully backward compatible **Rationale:** - Templates are metadata/documentation only - Example configs are reference materials (not deployed) - CHANGELOG documents existing functionality - No functional code changes ### Benefits for Users 1. **Bridge operators** - Now understand PT_PORT usage (official naming compatibility) 2. **All relay operators** - Clear guidance on bandwidth options (RelayBandwidth vs Bandwidth) 3. **Template users** - Inline comments explain configuration choices 4. **Contributors** - PR template ensures quality and consistency --- ## 📸 Screenshots / Logs <details> <summary>Click to expand: CHANGELOG.md additions</summary> ```markdown ### 📖 Configuration & Documentation Enhancements (Latest) * 🔧 **OBFS4V_* Variable Parsing (CRITICAL FIX)** - Fixed busybox regex incompatibility causing rejection of values with spaces - Issue: `OBFS4V_MaxMemInQueues="1024 MB"` was rejected with "dangerous characters" error - Solution: Rewrote validation (docker-entrypoint.sh:309-321) - Impact: Bridge operators can now use advanced memory/CPU settings * 🌉 **PT_PORT Support & Official Bridge Naming** - Added `PT_PORT` environment variable for drop-in compatibility - Full compatibility with official bridge ENV naming * 📊 **Bandwidth Configuration Clarification** - Documented TOR_BANDWIDTH_RATE/BURST → RelayBandwidthRate/Burst translation - Added Option 1 vs Option 2 explanations in all example configs * 📚 **Template & Example Updates** - 10 template files updated with bandwidth guidance - 3 example configs updated with PT_PORT and bandwidth options ``` </details> <details> <summary>Click to expand: Example config additions</summary> **relay-bridge.conf:** ```conf # Method 2: Using official Tor Project naming (drop-in compatibility) docker run -d \ --name tor-bridge \ --network host \ -e NICKNAME=MyBridge \ -e EMAIL="your-email@example.com" \ -e OR_PORT=9001 \ -e PT_PORT=9002 \ ... ``` **relay-exit.conf & relay-guard.conf:** ```conf Option 1: Relay-specific bandwidth (recommended for exit relays) RelayBandwidthRate 50 MBytes RelayBandwidthBurst 100 MBytes Option 2: Global bandwidth limits (applies to all Tor traffic) BandwidthRate 50 MBytes BandwidthBurst 100 MBytes Note: Use RelayBandwidthRate/Burst for exit relays to avoid limiting directory and other non-relay traffic. ``` </details> --- ## 👥 Reviewers **Suggested reviewers:** - @r3bo0tbx1 (maintainer) **For specific areas:** - **Documentation:** @r3bo0tbx1 - **Template accuracy:** @r3bo0tbx1 --- ## 📋 Pre-Submission Checklist ### Required - [x] I have read the [Contributing Guidelines](../CONTRIBUTING.md) - [x] I have read the [Code of Conduct](../CODE_OF_CONDUCT.md) - [x] My code follows the project's coding standards (documentation only) - [x] I have performed a self-review of my documentation - [x] My changes generate no new warnings or errors - [x] I have updated documentation as needed (comprehensive updates) - [x] I have added an entry to CHANGELOG.md under v1.1.1 - [x] All CI/CD checks pass (documentation changes only) ### Testing - [x] JSON templates validated with `python3 -m json.tool` - [x] YAML templates validated with `docker-compose config -q` - [x] Cross-references verified for accuracy - [x] Markdown formatting verified (no broken links) ### Optional (but recommended) - [x] Verified consistency across all 10 updated template files - [x] Verified CHANGELOG.md entry is comprehensive and accurate - [x] Created PR template for future contributor use --- ## 💬 Additional Notes ### Scope of Changes **4 commits in this PR:** 1. `44f371d` - Update example configs with PT_PORT and bandwidth options 2. `274d087` - Document bandwidth options and PT_PORT in templates and docs 3. `7a66dd7` - Update CHANGELOG.md with v1.1.1 configuration enhancements 4. `714c720` - Add comprehensive pull request template ### Why These Changes Matter 1. **OBFS4V Fix Documentation** - Critical fix was implemented in docker-entrypoint.sh but users needed to see it documented in CHANGELOG and examples 2. **PT_PORT Visibility** - Official bridge naming (OR_PORT/PT_PORT) enables drop-in replacement for `thetorproject/obfs4-bridge`, but examples didn't show this - now they do 3. **Bandwidth Clarity** - Users were confused about `RelayBandwidthRate` vs `BandwidthRate` - now every template/example explains the difference: - **RelayBandwidthRate/Burst** - Limits relay traffic only (recommended) - **BandwidthRate/Burst** - Limits ALL Tor traffic (directory, etc.) 4. **PR Template** - Ensures future contributions meet project quality standards with comprehensive checklists ### Ready for v1.1.1 Release This PR completes the v1.1.1 release documentation: - ✅ OBFS4V fix documented - ✅ PT_PORT support documented - ✅ Bandwidth options clarified - ✅ All templates updated - ✅ Examples comprehensive - ✅ CHANGELOG complete - ✅ PR template created **After merge:** Ready to tag v1.1.1 and trigger release workflow. --- **Thank you for reviewing!** 🧅✨ This PR ensures v1.1.1 users have complete, accurate documentation for all configuration options and improvements. **Questions?** - GitHub Discussions: https://github.com/r3bo0tbx1/tor-guard-relay/discussions - Issues: https://github.com/r3bo0tbx1/tor-guard-relay/issues
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
alpine
alpine
alpine
alpine
alpine
alpine
alpine
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
dependencies
docker
docker
docker
docker
docker
docker
docker
docker
docker
docker
docker
docker
docker
docker
enhancement
github-actions
github-actions
good first issue
security
security
security
security
security
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
MrUnknownDE
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github/tor-guard-relay#10
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?