{"id":28752990,"url":"https://github.com/johnwbyrd/fan2go-package","last_synced_at":"2025-09-15T08:15:55.536Z","repository":{"id":298590374,"uuid":"1000484885","full_name":"johnwbyrd/fan2go-package","owner":"johnwbyrd","description":"fan2go Debian/Ubuntu automated packaging","archived":false,"fork":false,"pushed_at":"2025-06-25T00:29:37.000Z","size":388,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T01:32:17.569Z","etag":null,"topics":["debian","debian-packages","debian-packaging","fan2go","ubuntu","ubuntu-packaging"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnwbyrd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T21:27:54.000Z","updated_at":"2025-06-17T21:41:18.000Z","dependencies_parsed_at":"2025-06-11T22:40:21.224Z","dependency_job_id":"c4571048-9ace-432a-a0cc-5c8785d25521","html_url":"https://github.com/johnwbyrd/fan2go-package","commit_stats":null,"previous_names":["johnwbyrd/fan2go-package"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/johnwbyrd/fan2go-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Ffan2go-package","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Ffan2go-package/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Ffan2go-package/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Ffan2go-package/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnwbyrd","download_url":"https://codeload.github.com/johnwbyrd/fan2go-package/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnwbyrd%2Ffan2go-package/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275225965,"owners_count":25427019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debian","debian-packages","debian-packaging","fan2go","ubuntu","ubuntu-packaging"],"created_at":"2025-06-17T00:05:42.619Z","updated_at":"2025-09-15T08:15:55.509Z","avatar_url":"https://github.com/johnwbyrd.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# fan2go Debian Packaging\n\nThis repository provides automated Debian packaging for [fan2go](https://github.com/markusressel/fan2go), a daemon to control system fans based on temperature readings. The packaging uses the `git-buildpackage` (gbp) workflow with full automation for upstream tracking, changelog management, and multi-distribution builds.\n\n## Features\n\n### Automated Workflow\n- **Daily upstream monitoring**: Automatically checks for new fan2go releases\n- **Smart version management**: Automatically updates `debian/changelog` with proper version handling\n- **Multi-distribution builds**: Builds packages for Debian bookworm, bullseye, and trixie\n- **Automated releases**: Creates GitHub releases with `.deb` packages and source files\n- **DEP-14 compliant**: Follows Debian packaging standards with proper branch structure\n\n### Build System\n- **Clean build environment**: Uses `git-buildpackage` with proper export directories\n- **Go modules support**: Handles complex Go dependency management\n- **Pristine source handling**: Maintains reproducible builds with `pristine-tar`\n- **Quality assurance**: Runs `lintian` checks on all packages\n\n## Installation\n\n### From GitHub Releases\n\n1. Download the latest `.deb` package for your distribution from the [Releases page](https://github.com/johnwbyrd/fan2go-package/releases)\n2. Install the package:\n   ```bash\n   sudo apt install ./fan2go_*_amd64.deb\n   ```\n3. Enable and start the service:\n   ```bash\n   sudo systemctl enable --now fan2go\n   ```\n\n### Package Contents\n\nThe package installs:\n- **Binary**: `/usr/bin/fan2go`\n- **Configuration**: `/etc/fan2go/fan2go.yaml` (default template)\n- **Service**: `fan2go.service` (systemd unit)\n- **Documentation**: Manual pages and examples\n\n## Repository Structure\n\nThis repository follows the DEP-14 standard for Debian packaging:\n\n### Branch Layout\n- **`main`**: Repository automation (GitHub Actions) and documentation\n- **`upstream`**: Pristine upstream source code from markusressel/fan2go\n- **`debian/unstable`**: Debian packaging files + upstream source (buildable)\n- **`pristine-tar`**: Metadata for reproducible source packages\n\n### Key Files\n- **`.github/workflows/updater.yml`**: Daily upstream monitoring and import\n- **`.github/workflows/build-test.yml`**: Multi-distribution package building\n- **`debian/`**: Complete Debian packaging configuration\n- **`CLAUDE.md`**: Detailed technical documentation and workflow guide\n\n## Automation Workflows\n\n### Upstream Updater (`updater.yml`)\nRuns daily at midnight UTC and:\n\n1. **Monitors upstream**: Uses `uscan` to check for new fan2go releases\n2. **Imports sources**: Uses `gbp import-orig` to import new upstream versions\n3. **Updates changelog**: Automatically updates `debian/changelog` with smart version management\n4. **Pushes changes**: Updates all relevant branches and tags\n5. **Triggers builds**: Starts automated package building for new versions\n\n### Build \u0026 Test (`build-test.yml`)\nTriggered by upstream updates and:\n\n1. **Multi-distribution builds**: Creates packages for bookworm, bullseye, and trixie\n2. **Clean environments**: Uses Docker containers for reproducible builds\n3. **Quality checks**: Runs `lintian` on all generated packages\n4. **Artifact management**: Collects `.deb`, `.dsc`, and build metadata\n5. **GitHub releases**: Creates releases with proper version naming\n\n### Smart Version Management\n\nThe automation handles two scenarios:\n\n**New Upstream Version** (e.g., 0.9.0 → 0.10.0):\n- Creates new changelog entry: `fan2go (0.10.0-1) unstable`\n- Uses `gbp dch --new-version=0.10.0-1`\n\n**Packaging Updates** (same upstream):\n- Increments Debian revision: `0.10.0-1` → `0.10.0-2`\n- Uses `dch -i` to increment properly\n\n## Local Development\n\n### Prerequisites\n\n```bash\n# Install build dependencies\nsudo apt install devscripts git-buildpackage pristine-tar golang-go libsensors-dev help2man\n\n# For clean chroot builds (recommended)\nsudo apt install pbuilder\n```\n\n### Building Packages\n\n#### Quick Build\n```bash\ngit clone https://github.com/johnwbyrd/fan2go-package.git\ncd fan2go-package\ngit checkout debian/unstable\n\n# Build in current environment\ngbp buildpackage --git-upstream-branch=upstream --git-debian-branch=debian/unstable -us -uc\n```\n\n#### Clean Build (Recommended)\n```bash\n# Set up pbuilder (one-time setup)\nsudo pbuilder create --distribution bookworm\n\n# Build in clean chroot\ngbp buildpackage --git-pbuilder --git-upstream-branch=upstream --git-debian-branch=debian/unstable\n```\n\n### Development Workflow\n\n1. **Make packaging changes** on the `debian/unstable` branch\n2. **Update changelog**: `dch -i` to add new entry\n3. **Test build**: `gbp buildpackage --git-ignore-new -us -uc`\n4. **Quality check**: `lintian ../*.deb`\n5. **Commit changes**: Standard git workflow\n\n### Importing New Upstream Versions\n\n```bash\n# Check for new versions\nuscan --verbose --report\n\n# Import new upstream version\ngbp import-orig --uscan --upstream-branch=upstream --debian-branch=debian/unstable --pristine-tar\n\n# Update changelog (done automatically in CI)\ngbp dch --new-version=NEW_VERSION-1 --distribution=unstable --release --spawn-editor=never\n\n# Push changes\ngit push origin upstream debian/unstable pristine-tar --tags\n```\n\n## Technical Challenges Solved\n\n### Go Modules + dh-golang Compatibility\n\nThis package overcomes significant challenges with packaging Go modules using `dh-golang`:\n\n**Issues Encountered**:\n- `dh-golang` was designed for GOPATH, not Go modules\n- Module cache dependency analysis breaks builds\n- Test environment conflicts with dependency resolution\n\n**Solutions Implemented**:\n- **Environment variables**: `GO111MODULE=on`, `GOPROXY=https://proxy.golang.org,direct`\n- **Limited scope**: `DH_GOLANG_BUILDPKG := ./cmd/...` to avoid module cache analysis\n- **Custom rules**: Override `dh_auto_build` and `dh_auto_test` for proper Go modules handling\n- **Build process**: Uses `make build` explicitly instead of relying on dh defaults\n\n### Build Environment Isolation\n\n**Challenge**: GitHub Actions workspace contamination affecting `dpkg-source`\n\n**Solution**: \n- Export builds to `/build-area` outside mounted workspace\n- Move artifacts back to mounted volume after build completion\n- Use `--git-ignore-new` for GitHub Actions temporary files\n\n## Configuration\n\n### Default Configuration\n\nThe package installs a template configuration at `/etc/fan2go/fan2go.yaml`. Key sections:\n\n```yaml\n# Database location (writable by fan2go service)\ndbPath: /var/lib/fan2go/fan2go.db\n\n# Sensor definitions (detect with 'fan2go detect')\nsensors:\n  - id: cpu_temp\n    hwmon:\n      platform: \"coretemp\"\n      index: 1\n\n# Fan definitions\nfans:\n  - id: cpu_fan\n    hwmon:\n      platform: \"nct6798\"\n      rpmChannel: 1\n      pwmChannel: 1\n    curve: cpu_curve\n\n# Temperature curves\ncurves:\n  - id: cpu_curve\n    linear:\n      sensor: cpu_temp\n      min: 40    # 40°C = minimum fan speed\n      max: 80    # 80°C = maximum fan speed\n```\n\n### Service Management\n\n```bash\n# Enable automatic startup\nsudo systemctl enable fan2go\n\n# Start service\nsudo systemctl start fan2go\n\n# Check status\nsudo systemctl status fan2go\n\n# View logs\njournalctl -u fan2go -f\n\n# Validate configuration\nsudo fan2go config validate\n```\n\n## Troubleshooting\n\n### Build Issues\n\n**Problem**: `gbp buildpackage` fails with git repository errors\n```bash\n# Solution: Use export directory\ngbp buildpackage --git-export-dir=../build-area --git-ignore-new\n```\n\n**Problem**: Go module dependency errors\n```bash\n# Solution: Ensure proper environment\nexport GO111MODULE=on\nexport GOPROXY=https://proxy.golang.org,direct\n```\n\n### Runtime Issues\n\n**Problem**: Permission denied accessing sensors\n```bash\n# Solution: Ensure user is in appropriate groups\nsudo usermod -a -G sensors $USER\n# Or run as root (recommended for systemd service)\n```\n\n**Problem**: No sensors detected\n```bash\n# Solution: Set up lm-sensors first\nsudo sensors-detect\nsudo modprobe \u003cdetected_modules\u003e\n```\n\n### Package Issues\n\n**Problem**: Dependency conflicts\n```bash\n# Solution: Fix dependencies\nsudo apt install -f\n```\n\n**Problem**: Configuration file conflicts\n```bash\n# Solution: Back up custom config before upgrade\nsudo cp /etc/fan2go/fan2go.yaml /etc/fan2go/fan2go.yaml.backup\n```\n\n## Contributing\n\n### Reporting Issues\n\n- **Packaging issues**: Report to this repository\n- **Software bugs**: Report to [upstream fan2go](https://github.com/markusressel/fan2go/issues)\n\n### Submitting Changes\n\n1. **Fork** this repository\n2. **Create branch** from `debian/unstable`\n3. **Make changes** to packaging files in `debian/`\n4. **Test build** locally\n5. **Submit pull request** against `debian/unstable` branch\n\n### Workflow Guidelines\n\n- **Packaging changes**: Target `debian/unstable` branch\n- **Automation changes**: Target `main` branch\n- **Version updates**: Handled automatically, no manual PRs needed\n- **Testing**: Always test builds before submitting\n\n## Resources\n\n### Documentation\n- [Upstream fan2go](https://github.com/markusressel/fan2go)\n- [Debian New Maintainer's Guide](https://www.debian.org/doc/manuals/maint-guide/)\n- [git-buildpackage Manual](https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/)\n- [DEP-14 Specification](https://dep-team.pages.debian.net/deps/dep14/)\n\n### Tools\n- [lm-sensors Setup](https://wiki.archlinux.org/title/Lm_sensors)\n- [fan2go-tui](https://github.com/markusressel/fan2go-tui) - Terminal UI for fan2go\n\n### Support\n- **GitHub Issues**: Package-specific problems\n- **Debian Packaging**: [debian-mentors mailing list](https://lists.debian.org/debian-mentors/)\n- **fan2go Usage**: [Upstream documentation](https://github.com/markusressel/fan2go)\n\n## License\n\n- **Packaging files** (`debian/`): Licensed under the same terms as fan2go (AGPL-3.0)\n- **Automation scripts**: Licensed under AGPL-3.0\n- **fan2go software**: Licensed under AGPL-3.0 by Markus Ressel\n\nSee `debian/copyright` for detailed licensing information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnwbyrd%2Ffan2go-package","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnwbyrd%2Ffan2go-package","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnwbyrd%2Ffan2go-package/lists"}