🔖 release(v1.1.6): bind mount fix, full repo audit, workflow fixes

🔧 Entrypoint: - Detect wrong ownership on /var/lib/tor and /var/lib/tor/keys at startup with actionable chown commands before Tor fails cryptically in Phase 4 - Accept DEBUG=TRUE, DEBUG=1, DEBUG=yes (case-insensitive) - Fix signal trap bug: inner cleanup_verify_tmp no longer overwrites the global TERM/INT handler (could skip graceful shutdown) 🛡️ Security: - Deprecate all versions < v1.1.5 (CVE-2025-15467, OpenSSL CVSS 9.8) - Add deprecation notice to README and SECURITY.md - Update lifecycle tables in CHANGELOG and SECURITY 🐛 Bug Fixes: - Fix bootstrap detection in migrate-from-official.sh (parsed non-existent "bootstrap_percent" field — now "bootstrap") - Fix health JSON docs across 4 files: uptime_seconds → uptime, add missing pid/errors fields, correct reachable type to string - Fix validate.yml: bash -n → sh -n (POSIX script, not bash) 📚 Documentation: - Add "Bind Mount Ownership" troubleshooting section to README - Fix chown 1000:1000 typo → 100:101 in TROUBLESHOOTING-BRIDGE-MIGRATION.md - Add [1.1.6] changelog entry - Update version references across 20+ files to v1.1.6 - Update 47x alpine:3.22.2 → 3.23.3 across migration docs/scripts - Fix tool count 4 → 5 in DEPLOYMENT, ARCHITECTURE, TROUBLESHOOTING - Remove 5 broken links (CLAUDE.md, CONTRIBUTORS.md, SECURITY-AUDIT-REPORT.md) - Fix stale image tags (:1.1.1/:1.1.2 → :latest) in 4 files - Rewrite PR template as clean reusable form ⚙️ Workflow (release.yml): - Fix duplicate title in release body (name + body both had ## 🧅 header) - Fix trailing --- not being stripped from changelog extract - Fix Full Changelog link comparing current tag to itself - Extract Alpine version from Dockerfile instead of hardcoding - Add fetch-depth: 0 for git history in release-notes job - Fix fallback commit range when no conventional commits found 🐳 Dockerfiles: - Fix stale base.name label (alpine:3.23.0 → alpine:3.23.3) - Fix trailing whitespace after backslash in Dockerfile.edge 📋 Templates: - Update cosmos-compose and docker-compose versions to 1.1.6
2026-04-06 00:32:04 +02:00 · 2026-02-08 16:04:22 +05:30
parent 3a4372f9c9
commit 90b65ee469
36 changed files with 302 additions and 527 deletions
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,15 +1,18 @@
 ## 📋 PR Type

- [x] 📚 **Documentation** (changes to documentation only)
- [x] 🔧 **Configuration** (changes to templates, examples, or deployment configs)
+- [ ] 🐛 **Bug fix** (non-breaking change that fixes an issue)
+- [ ] ✨ **New feature** (non-breaking change that adds functionality)
+- [ ] 💥 **Breaking change** (fix or feature that would cause existing functionality to change)
+- [ ] 📚 **Documentation** (changes to documentation only)
+- [ ] 🔧 **Configuration** (changes to templates, examples, or deployment configs)
+- [ ] 🛡️ **Security** (security patch or hardening)
+- [ ] 🏗️ **Build/CI** (changes to build process or CI/CD)

 ---

 ## 🔗 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.
+- Fixes #

 ---

@@ -17,274 +20,42 @@

 ### 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
+- **Image Version:**
+- **Deployment Method:**
+- **Architecture:**

-**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
-```
+### Steps to Test
+
+1. 
+2. 
+3. 

 ---

 ## 💥 Breaking Changes

- [x] **No breaking changes**
+- [ ] **No breaking changes**

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

 ---

-## 📚 Documentation Updates
+## ✅ Pre-Submission Checklist

- [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
+- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md)
+- [ ] I have read the [Code of Conduct](../CODE_OF_CONDUCT.md)
+- [ ] My code follows the project's coding standards
+- [ ] I have performed a self-review of my changes
+- [ ] My changes generate no new warnings or errors
+- [ ] I have updated documentation as needed
+- [ ] I have added an entry to CHANGELOG.md (if applicable)
+- [ ] I have removed sensitive information from logs/config examples
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -154,7 +154,7 @@ jobs:
            dockerfile: Dockerfile
            suffix: ""
            is_latest: "true"
-            base: "Alpine 3.22.2"
+            base: "Alpine 3.23.3"
            push_dockerhub: "true"
          - name: edge
            dockerfile: Dockerfile.edge
@@ -441,6 +441,8 @@ jobs:
    steps:
      - name: 📥 Checkout Repository
        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0

      - name: 📝 Generate Notes
        run: |
@@ -465,15 +467,19 @@ jobs:
            ' CHANGELOG.md > tmp_notes.txt

            if [ -s tmp_notes.txt ]; then
-              sed -i '${/^---[[:space:]]*$/d;}' tmp_notes.txt
-              sed -i ':a; /^[ \n\r\t]*$/ { $d; N; ba }' tmp_notes.txt 2>/dev/null || true
+              # Strip trailing blank lines and --- separators from changelog extract
+              while [ -s tmp_notes.txt ]; do
+                LAST_LINE=$(tail -1 tmp_notes.txt)
+                case "$(printf '%s' "$LAST_LINE" | tr -d '[:space:]')" in
+                  ""|"---") sed -i '$ d' tmp_notes.txt ;;
+                  *) break ;;
+                esac
+              done

              echo "✅ Found changelog section for v${VERSION} in CHANGELOG.md"
              CHANGELOG_FOUND=1

-              echo "## 🧅 Tor Guard Relay v${VERSION}" > release_notes.md
-              echo "" >> release_notes.md
-              cat tmp_notes.txt >> release_notes.md
+              cat tmp_notes.txt > release_notes.md
            else
              echo "⚠️ No changelog section found for v${VERSION} in CHANGELOG.md"
            fi
@@ -486,14 +492,24 @@ jobs:

            if [ -x scripts/release/generate-release-notes.sh ]; then
              chmod +x scripts/release/generate-release-notes.sh
-              ./scripts/release/generate-release-notes.sh --format github "${VERSION}" > release_notes.md
+              ./scripts/release/generate-release-notes.sh --format github "${VERSION}" > tmp_auto_notes.md
+              # Strip title (release 'name' already shows it) and footer (workflow appends its own)
+              sed '/^## 🧅/d; /^\*\*Full Changelog\*\*/d' tmp_auto_notes.md > release_notes.md
+              # Remove trailing --- and blank lines left by the script footer
+              while [ -s release_notes.md ]; do
+                LAST_LINE=$(tail -1 release_notes.md)
+                case "$(printf '%s' "$LAST_LINE" | tr -d '[:space:]')" in
+                  ""|"---") sed -i '$ d' release_notes.md ;;
+                  *) break ;;
+                esac
+              done
              echo "✅ Auto-generated release notes from conventional commits"
            else
-              echo "## 🧅 Tor Guard Relay v${VERSION}" > release_notes.md
+              echo "### Changes" > release_notes.md
              echo "" >> release_notes.md
-              echo "### Changes" >> release_notes.md
-              echo "" >> release_notes.md
-              git log --pretty=format:"- %s (\`%h\`) by %an" "$(git describe --tags --abbrev=0)..HEAD" >> release_notes.md || echo "- Initial release" >> release_notes.md
+              PREV_TAG=$(git tag --sort=-v:refname | grep -v "^v${VERSION}$" | head -1)
+              [ -z "$PREV_TAG" ] && PREV_TAG=$(git rev-list --max-parents=0 HEAD)
+              git log --pretty=format:"- %s (\`%h\`) by %an" "${PREV_TAG}..HEAD" >> release_notes.md || echo "- Initial release" >> release_notes.md
              echo "" >> release_notes.md
              echo "⚠️ **Note:** Release notes were auto-generated from commit history." >> release_notes.md
              echo "For detailed changes, see the commit history below." >> release_notes.md
@@ -503,12 +519,14 @@ jobs:

          echo "" >> release_notes.md
          echo "---" >> release_notes.md
+          ALPINE_VERSION=$(grep -oP '^FROM alpine:\K[0-9.]+' Dockerfile 2>/dev/null || echo "latest")
+
          echo "" >> release_notes.md
          echo "### 🐳 Docker Images" >> release_notes.md
          echo "" >> release_notes.md
          echo "**Stable Variant (Recommended for Production)**" >> release_notes.md
          echo "" >> release_notes.md
-          echo "- Base: Alpine 3.22.2" >> release_notes.md
+          echo "- Base: Alpine ${ALPINE_VERSION}" >> release_notes.md
          echo "- Proven stability with weekly security updates" >> release_notes.md
          echo "" >> release_notes.md
          echo "\`\`\`bash" >> release_notes.md
@@ -547,7 +565,9 @@ jobs:
          echo "" >> release_notes.md
          echo "---" >> release_notes.md
          echo "" >> release_notes.md
-          echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/$(git describe --tags --abbrev=0 2>/dev/null || echo 'v1.0.0')...v${VERSION}" >> release_notes.md
+          PREV_TAG=$(git tag --sort=-v:refname | grep -v "^v${VERSION}$" | head -1)
+          [ -z "$PREV_TAG" ] && PREV_TAG="v1.0.0"
+          echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/${PREV_TAG}...v${VERSION}" >> release_notes.md

          echo ""
          echo "✅ Release notes generation complete"
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -65,7 +65,7 @@ jobs:
          # Check main entrypoint script
          if [ -f docker-entrypoint.sh ]; then
            echo "📄 Checking docker-entrypoint.sh..."
-            bash -n docker-entrypoint.sh || exit 1
+            sh -n docker-entrypoint.sh || exit 1
            echo "   ✅ docker-entrypoint.sh syntax valid"
          fi