Major refactor of Docker Compose configurations and tooling enhancements.
- ✨ Add `gen-auth` script for generating Tor Control Port credentials
- 🐳 Refactor Docker Compose templates:
- Add native healthcheck configurations to all relay/bridge files
- Standardize security capabilities (drop ALL, add SETUID/SETGID)
- Remove verbose comments to streamline template usage
- Update volume definitions for better data persistence
- 🔧 Update base dependencies:
- Alpine Linux -> 3.23.0
- Golang -> 1.25.5-alpine
- 🧹 Standardize ENV variable names across all configurations
Recent Alpine base images introduce a 'klogd' user at UID 100, which forced
the 'tor' package to install as UID 101. This caused "Permission denied"
errors for existing data volumes owned by UID 100.
This fix:
- Removes the conflicting 'klogd' user
- Manually creates the 'tor' user with fixed UID 100 / GID 101
- Ensures compatibility with existing persistent volumes
This commit addresses high-severity vulnerabilities detected by Docker Scout in both the Lyrebird binary and the Alpine base image.
Changes:
- Lyrebird: Implemented a multi-stage build using golang:1.24-alpine. This compiles Lyrebird from source to resolve "baked-in" Go runtime and dependency vulnerabilities (stdlib, crypto, pion) found in the upstream Alpine package.
- Base OS: Added apk upgrade --no-cache to force the installation of the latest system libraries, patching active CVEs in musl and openssl.
Resolves: CVE-2025-9230 (openssl), CVE-2025-26519 (musl), and multiple Go runtime CVEs.
This commit addresses high-severity vulnerabilities detected by Docker Scout in both the Lyrebird binary and the Alpine base image.
Changes:
- Lyrebird: Implemented a multi-stage build using golang:1.24-alpine. This compiles Lyrebird from source to resolve "baked-in" Go runtime and dependency vulnerabilities (stdlib, crypto, pion) found in the upstream Alpine package.
- Base OS: Added apk upgrade --no-cache to force the installation of the latest system libraries, patching active CVEs in musl and openssl.
Resolves: CVE-2025-9230 (openssl), CVE-2025-26519 (musl), and multiple Go runtime CVEs.
- Implements multi-stage build in `Dockerfile` and `Dockerfile.edge` using `golang:1.24-alpine` to compile `lyrebird` from official source.
- Resolves high-severity vulnerabilities in `stdlib`, `crypto`, and `pion` by enforcing latest Go runtime and dependency updates (`go get -u`).
- Maintains minimal image footprint by discarding the build toolchain and copying only the stripped binary to the final Alpine image.
- 📘 Added comprehensive docs including FAQ, architecture, and migration guides
- 🧩 Introduced new and updated example configs and templates
- 🧾 Added a pull request template for contributor workflow
- 🧪 Enhanced CI/CD with SBOM generation and improved release notes
- 🛡️ Expanded Trivy security scanning coverage in pipelines
- 🔗 Updated README to reference new docs and the quick start script
- 📘 Added comprehensive docs including FAQ, architecture, and migration guides
- 🧩 Introduced new and updated example configs and templates
- 🧾 Added a pull request template for contributor workflow
- 🧪 Enhanced CI/CD with SBOM generation and improved release notes
- 🛡️ Expanded Trivy security scanning coverage in pipelines
- 🔗 Updated README to reference new docs and the quick start script
- 📘 Added comprehensive docs including FAQ, architecture, and migration guides
- 🧩 Introduced new and updated example configs and templates
- 🧾 Added a pull request template for contributor workflow
- 🧪 Enhanced CI/CD with SBOM generation and improved release notes
- 🛡️ Expanded Trivy security scanning coverage in pipelines
- 🔗 Updated README to reference new docs and the quick start script
- 🎨 Applied full cyber dark theme with neon headers and panel styling
- 🧩 Reorganized sections for better readability and navigation
- 📘 Added upgraded formatting for diagnostic, monitoring, and deployment areas
- 🧱 Improved visual consistency across examples, tables, and code blocks
- ✨ Updated badges and layout for a cleaner top section
🚀 Major architectural release with a near full rewrite of the entrypoint, validation system, diagnostics, and templates. The image is now ~20MB, fully busybox based, more secure, and more flexible for relay and bridge operators.
🔧 Critical Fixes
- Busybox compatible rewrite of OBFS4V_* parsing for values with spaces.
- Rewritten TOR_CONTACT_INFO validation to prevent crash loops.
- Restored bootstrap logs with Log notice stdout.
- Fixed ENV healthchecks and validation order.
- Resolved busybox regex and quoting issues across the script.
✨ Features and Enhancements
- Added PT_PORT with complete obfs4 bridge compatibility.
- Support for OR_PORT, PT_PORT, EMAIL, and NICKNAME.
- Rewritten bandwidth logic with correct Rate and Burst translation.
- Unified guard, exit, and bridge via TOR_RELAY_MODE.
- Integrated obfs4 with rewritten diagnostics for status, health, fingerprint, and bridge-line.
- Reliable ENV only mode without torrc files.
📦 Build Improvements
- Image reduced ~45MB to ~20MB with busybox only tools.
- Rewritten healthcheck for ENV and mounted configs.
- Four diagnostic tools rewritten to pure busybox sh.
- Weekly rebuilds with latest Alpine and Tor.
📚 Templates and Documentation
- All templates rewritten and updated with bandwidth options and naming alternatives.
- Updated Cosmos and Docker Compose templates for bridge, guard, exit.
- New templates README with full deployment, migration, and config comparisons.
- Revised Claude file with clearer differences and bandwidth notes.
🔒 Security Hardening
- 32 vulnerabilities fixed across critical, high, medium, low categories.
- Non root runtime with UID 100.
- Strict OBFS4V_* whitelist and rewritten validation.
- No exposed diagnostics ports, docker exec only.
- Smaller attack surface with removed binaries.
🚀 Migration Notes
- From v1.1.0: direct upgrade, no config changes, fingerprint preserved.
- From official obfs4 bridge: one time UID fix required, full ENV compatibility afterward.
- Templates include both TOR_ and official naming for smooth migration.
🧩 Compatibility
- Alpine 3.22.2 base, latest Tor from edge.
- AMD64 and ARM64 supported.
- Works with Docker, Compose, Cosmos Cloud, Portainer.
- Consolidated CI into one efficient pipeline
- Unified tag handling for GHCR and Docker Hub
- Added weekly + manual release triggers
- Hardened dos2unix normalization pre-build
- Cleaner YAML and quieter logs
BREAKING CHANGE: Internal services now bind exclusively to 127.0.0.1 by default.
This release introduces strict network boundary enforcement and build-level hardening
to improve both runtime security and CI/CD compliance.
Port Security Model:
- Public: 9001 (ORPort), 9030 (DirPort)
- Internal: 9035+ (metrics, health, dashboard) - localhost-only
Security Enhancements:
- Enforces localhost binding for all internal services
- Prevents unauthorized external access to internal endpoints
- Adds reverse proxy, SSH tunnel, and VPN access guidance
- Integrates automated port security validation in diagnostic tools
- Includes comprehensive migration instructions for existing deployments
Build Improvements:
- Dockerfile hardened with strict shell mode (set -euo pipefail)
- Fixed lint warnings: DL3018, DL3059, SC2010, DL4006
- Ensures reproducible builds and cleaner CI validation
- No functional runtime changes beyond improved reliability
File Updates:
- CHANGELOG.md: Version entries updated to v1.0.2
- README.md: Deployment examples and version references aligned
- SECURITY.md: Expanded with port access policy and network architecture
- relay-status.sh: Added port binding validation (v1.0.2)
- integration-check.sh: Added version and port validation phases (v1.0.2)
- Dockerfile: Hardened, lint-compliant, and security aligned
Migration Required:
If external access to metrics or health endpoints is required,
configure a reverse proxy with authentication, SSH tunneling, or VPN routing.
See SECURITY.md for implementation details.
Version: 1.0.2
BREAKING CHANGE: Internal services now bind exclusively to 127.0.0.1 by default.
This release introduces strict network boundary enforcement and build-level hardening
to improve both runtime security and CI/CD compliance.
Port Security Model:
- Public: 9001 (ORPort), 9030 (DirPort)
- Internal: 9035+ (metrics, health, dashboard) - localhost-only
Security Enhancements:
- Enforces localhost binding for all internal services
- Prevents unauthorized external access to internal endpoints
- Adds reverse proxy, SSH tunnel, and VPN access guidance
- Integrates automated port security validation in diagnostic tools
- Includes comprehensive migration instructions for existing deployments
Build Improvements:
- Dockerfile hardened with strict shell mode (set -euo pipefail)
- Fixed lint warnings: DL3018, DL3059, SC2010, DL4006
- Ensures reproducible builds and cleaner CI validation
- No functional runtime changes beyond improved reliability
File Updates:
- CHANGELOG.md: Version entries updated to v1.0.2
- README.md: Deployment examples and version references aligned
- SECURITY.md: Expanded with port access policy and network architecture
- relay-status.sh: Added port binding validation (v1.0.2)
- integration-check.sh: Added version and port validation phases (v1.0.2)
- Dockerfile: Hardened, lint-compliant, and security aligned
Migration Required:
If external access to metrics or health endpoints is required,
configure a reverse proxy with authentication, SSH tunneling, or VPN routing.
See SECURITY.md for implementation details.
Version: 1.0.2
BREAKING CHANGE: Internal services now bind exclusively to 127.0.0.1 by default.
This release introduces strict network boundary enforcement and build-level hardening
to improve both runtime security and CI/CD compliance.
Port Security Model:
- Public: 9001 (ORPort), 9030 (DirPort)
- Internal: 9035+ (metrics, health, dashboard) - localhost-only
Security Enhancements:
- Enforces localhost binding for all internal services
- Prevents unauthorized external access to internal endpoints
- Adds reverse proxy, SSH tunnel, and VPN access guidance
- Integrates automated port security validation in diagnostic tools
- Includes comprehensive migration instructions for existing deployments
Build Improvements:
- Dockerfile hardened with strict shell mode (set -euo pipefail)
- Fixed lint warnings: DL3018, DL3059, SC2010, DL4006
- Ensures reproducible builds and cleaner CI validation
- No functional runtime changes beyond improved reliability
File Updates:
- CHANGELOG.md: Version entries updated to v1.0.2
- README.md: Deployment examples and version references aligned
- SECURITY.md: Expanded with port access policy and network architecture
- relay-status.sh: Added port binding validation (v1.0.2)
- integration-check.sh: Added version and port validation phases (v1.0.2)
- Dockerfile: Hardened, lint-compliant, and security aligned
Migration Required:
If external access to metrics or health endpoints is required,
configure a reverse proxy with authentication, SSH tunneling, or VPN routing.
See SECURITY.md for implementation details.
Version: 1.0.2
This commit finalizes the v1.0.2 release with a fully lint-compliant Dockerfile.
Changes:
- Dockerfile: strict shell mode with pipefail
- Dockerfile: resolved DL3018, DL3059, SC2010, DL4006 warnings
- Dockerfile: merged original features with compliance improvements
No functional or runtime changes, only build and CI reliability enhancements.
Version: 1.0.2
