DAW/furt

Fork 0

Package Distribution Strategy: Forgejo Packages + GitHub Mirror für Open Source #88

New issue

Closed

opened 2025-08-14 06:27:07 +02:00 by michael · 2 comments

michael commented

2025-08-14 06:27:07 +02:00

Owner

Package Distribution Problem

Current situation:

No structured release packages
No clear download strategy for Open Source users
Manual deployment only (not scalable for community)

Distribution Strategy

1. Forgejo Generic Packages (Primary)

Location: https://smida.dragons-at-work.de/DAW/furt/packages

Package naming convention:

furt-api-gateway-v1.0.0.tar.gz    # Clear, descriptive names
furt-api-gateway-v1.1.0.tar.gz    # Version tracking
furt-api-gateway-latest.tar.gz    # Convenience symlink

Upload automation:

# scripts/build-package.sh
VERSION=${1:-$(date +%Y%m%d)}
PACKAGE_NAME="furt-api-gateway-v${VERSION}.tar.gz"

# Create clean package (exclude dev files)
tar czf "$PACKAGE_NAME" \
  --exclude='.git' \
  --exclude='*.tmp' \
  --exclude='tests/' \
  src/ config/ scripts/ docs/ README.md

# Upload to Forgejo Packages via API
curl -X PUT \
  -H "Authorization: token $FORGEJO_TOKEN" \
  -T "$PACKAGE_NAME" \
  "https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/${VERSION}/${PACKAGE_NAME}"

2. GitHub Mirror (Secondary)

Purpose: Broader Open Source community reach

Setup:

Mirror furt repository to GitHub: dragons-at-work/furt
GitHub Releases with same package naming
Automatic sync from Forgejo tags

Benefits:

Better discoverability for Open Source users
GitHub's superior release/download UX
More familiar for developers

3. Download Documentation

Installation Wiki section:

# Download Options

## Option 1: Git Clone (Recommended for developers)
git clone https://github.com/dragons-at-work/furt.git furt-api-gateway
cd furt-api-gateway
git checkout v1.0.0

## Option 2: Package Download (Recommended for deployment)
# Forgejo (primary)
curl -O https://smida.dragons-at-work.de/DAW/furt/packages/generic/furt-api-gateway/1.0.0/furt-api-gateway-v1.0.0.tar.gz

# GitHub (mirror)
curl -L -O https://github.com/dragons-at-work/furt/releases/download/v1.0.0/furt-api-gateway-v1.0.0.tar.gz

tar xzf furt-api-gateway-v1.0.0.tar.gz
cd furt-api-gateway-v1.0.0

Versioning Strategy (SemVer)

v1.x.x: Compatible API, config-compatible
x.2.x: New features, no breaking changes
x.x.3: Bugfixes only

Release Process:

Tag release: git tag v1.0.0
Build package: ./scripts/build-package.sh 1.0.0
Upload to Forgejo Packages
Sync to GitHub Mirror
Update documentation

Package Contents Structure

Clean package contents:

furt-api-gateway-v1.0.0/
├── src/                    # Lua/C source
├── config/                 # Config templates
├── scripts/                # Small helper scripts (<100 lines)
├── docs/                   # Installation/config docs
├── examples/               # Distribution-specific examples
├── README.md               # Open Source-ready
├── VERSION                 # Version file
└── LICENSE                 # Open Source license

Excluded from packages:

.git/ directory
Development tools
Test files
Build artifacts
Personal configs with secrets

Implementation Tasks

Package Build System

Create scripts/build-package.sh for clean package creation
Implement Forgejo Packages API upload
Add package content validation
Create VERSION file management

GitHub Mirror Setup

Create GitHub repository: dragons-at-work/furt
Setup automatic mirroring from Forgejo
Configure GitHub Releases with same packages
Test download workflows

Documentation

Add package download section to Wiki
Document release process for maintainers
Create distribution-specific installation guides
Add troubleshooting for package installations

Automation

CI/CD for automatic package building on tags
Release notes generation from git commits
Package integrity verification (checksums)

Success Criteria

Open Source users can easily download and install furt
Clear package naming prevents download confusion
Automated release process for maintainers
Multiple download options for different user preferences
Proper versioning for upgrades and compatibility

Priority

High for v0.1.0 - Essential for Open Source release readiness

Issue DAW/furt#86: Repository Redesign (clean package structure)
Issue DAW/furt#71: Config Strategy (affects package contents)
Issue DAW/furt#87: Wiki Documentation (installation guides)

## Package Distribution Problem **Current situation:** - No structured release packages - No clear download strategy for Open Source users - Manual deployment only (not scalable for community) ## Distribution Strategy ### 1. Forgejo Generic Packages (Primary) **Location:** https://smida.dragons-at-work.de/DAW/furt/packages **Package naming convention:** ``` furt-api-gateway-v1.0.0.tar.gz # Clear, descriptive names furt-api-gateway-v1.1.0.tar.gz # Version tracking furt-api-gateway-latest.tar.gz # Convenience symlink ``` **Upload automation:** ```bash # scripts/build-package.sh VERSION=${1:-$(date +%Y%m%d)} PACKAGE_NAME="furt-api-gateway-v${VERSION}.tar.gz" # Create clean package (exclude dev files) tar czf "$PACKAGE_NAME" \ --exclude='.git' \ --exclude='*.tmp' \ --exclude='tests/' \ src/ config/ scripts/ docs/ README.md # Upload to Forgejo Packages via API curl -X PUT \ -H "Authorization: token $FORGEJO_TOKEN" \ -T "$PACKAGE_NAME" \ "https://smida.dragons-at-work.de/api/packages/DAW/generic/furt-api-gateway/${VERSION}/${PACKAGE_NAME}" ``` ### 2. GitHub Mirror (Secondary) **Purpose:** Broader Open Source community reach **Setup:** - Mirror furt repository to GitHub: dragons-at-work/furt - GitHub Releases with same package naming - Automatic sync from Forgejo tags **Benefits:** - Better discoverability for Open Source users - GitHub's superior release/download UX - More familiar for developers ### 3. Download Documentation **Installation Wiki section:** ```markdown # Download Options ## Option 1: Git Clone (Recommended for developers) git clone https://github.com/dragons-at-work/furt.git furt-api-gateway cd furt-api-gateway git checkout v1.0.0 ## Option 2: Package Download (Recommended for deployment) # Forgejo (primary) curl -O https://smida.dragons-at-work.de/DAW/furt/packages/generic/furt-api-gateway/1.0.0/furt-api-gateway-v1.0.0.tar.gz # GitHub (mirror) curl -L -O https://github.com/dragons-at-work/furt/releases/download/v1.0.0/furt-api-gateway-v1.0.0.tar.gz tar xzf furt-api-gateway-v1.0.0.tar.gz cd furt-api-gateway-v1.0.0 ``` ## Versioning Strategy (SemVer) **v1.x.x:** Compatible API, config-compatible **x.2.x:** New features, no breaking changes **x.x.3:** Bugfixes only **Release Process:** 1. Tag release: `git tag v1.0.0` 2. Build package: `./scripts/build-package.sh 1.0.0` 3. Upload to Forgejo Packages 4. Sync to GitHub Mirror 5. Update documentation ## Package Contents Structure **Clean package contents:** ``` furt-api-gateway-v1.0.0/ ├── src/ # Lua/C source ├── config/ # Config templates ├── scripts/ # Small helper scripts (<100 lines) ├── docs/ # Installation/config docs ├── examples/ # Distribution-specific examples ├── README.md # Open Source-ready ├── VERSION # Version file └── LICENSE # Open Source license ``` **Excluded from packages:** - .git/ directory - Development tools - Test files - Build artifacts - Personal configs with secrets ## Implementation Tasks ### Package Build System - [ ] Create scripts/build-package.sh for clean package creation - [ ] Implement Forgejo Packages API upload - [ ] Add package content validation - [ ] Create VERSION file management ### GitHub Mirror Setup - [ ] Create GitHub repository: dragons-at-work/furt - [ ] Setup automatic mirroring from Forgejo - [ ] Configure GitHub Releases with same packages - [ ] Test download workflows ### Documentation - [ ] Add package download section to Wiki - [ ] Document release process for maintainers - [ ] Create distribution-specific installation guides - [ ] Add troubleshooting for package installations ### Automation - [ ] CI/CD for automatic package building on tags - [ ] Release notes generation from git commits - [ ] Package integrity verification (checksums) ## Success Criteria - Open Source users can easily download and install furt - Clear package naming prevents download confusion - Automated release process for maintainers - Multiple download options for different user preferences - Proper versioning for upgrades and compatibility ## Priority **High for v0.1.0** - Essential for Open Source release readiness ## Related Issues - Issue DAW/furt#86: Repository Redesign (clean package structure) - Issue DAW/furt#71: Config Strategy (affects package contents) - Issue DAW/furt#87: Wiki Documentation (installation guides)

michael added the

labels 2025-08-14 06:27:07 +02:00

michael added this to the v0.1.2 - Gateway Basics milestone 2025-08-14 06:27:37 +02:00

michael referenced this issue

2025-08-14 16:03:38 +02:00

Config-Strategy Research: Distribution Best Practices für Open Source (Research Phase) #71

michael referenced this issue

2025-08-15 12:21:05 +02:00

Wiki-based Documentation: Replace monster scripts with user-friendly guides #87

michael referenced this issue

2025-08-15 16:07:13 +02:00

Implement API file versioning system for deployment tracking #83

michael referenced this issue

2025-08-15 17:27:33 +02:00

Session Handover: Issue-Cleanup + Deployment-Pipeline Status #92

michael commented

2025-08-15 17:36:03 +02:00

Author

Owner

SCOPE REDUCTION - Focus on Internal Distribution

GitHub Mirror → Separate Issue
Removing GitHub Mirror complexity from DAW/furt#88 for cleaner implementation.

DAW/furt#88 NEW SCOPE - Forgejo Packages Only:

Forgejo Generic Packages (Primary)
Build scripts for internal walter → tiamat pipeline
Package naming convention
Upload automation via Forgejo API
Clean package structure (exclude dev files)

Benefits:

Simpler implementation
No external dependencies
Faster delivery for DAW/furt#75 STARTTLS blocker
Internal pipeline focus

GitHub Mirror: New separate issue for Open Source community reach.

## SCOPE REDUCTION - Focus on Internal Distribution **GitHub Mirror → Separate Issue** Removing GitHub Mirror complexity from DAW/furt#88 for cleaner implementation. **DAW/furt#88 NEW SCOPE - Forgejo Packages Only:** - Forgejo Generic Packages (Primary) - Build scripts for internal walter → tiamat pipeline - Package naming convention - Upload automation via Forgejo API - Clean package structure (exclude dev files) **Benefits:** - Simpler implementation - No external dependencies - Faster delivery for DAW/furt#75 STARTTLS blocker - Internal pipeline focus **GitHub Mirror:** New separate issue for Open Source community reach.

michael added

and removed

labels 2025-08-15 17:36:58 +02:00

michael referenced this issue

2025-08-15 17:37:56 +02:00

GitHub Mirror for Open Source Community Distribution #93

michael referenced this issue

2025-08-15 18:39:41 +02:00

Wiki-based Documentation: Replace monster scripts with user-friendly guides #87

michael referenced this issue

2025-08-15 19:19:23 +02:00

Wiki-based Documentation: Replace monster scripts with user-friendly guides #87

michael referenced this issue from a commit

2025-09-03 20:28:04 +02:00

feat(distribution): add clean package build system

michael commented

2025-09-03 20:29:07 +02:00

Author

Owner

Implementation Update - Build System Ready

Completed:

✅ scripts/build-package.sh - Clean package creation with VCS-agnostic support
✅ Package structure validation - Excludes dev files, includes production essentials
✅ Version detection - Auto-detection from VERSION file or git tags
✅ Secure exclusions - No secrets, logs, or development artifacts in packages

Package Output:

./scripts/build-package.sh 0.1.1
# Creates: dist/furt-api-gateway-v0.1.1.tar.gz

Upload automation implemented locally (not committed for security) with:

Forgejo Generic Package API integration
Automatic .env config loading
HTTP error handling and user feedback
Download instructions generation

Ready for walter → tiamat pipeline testing once DAW/furt#75 STARTTLS is resolved.
Next: Package build integration into deployment workflow.

## Implementation Update - Build System Ready **Completed:** - ✅ **scripts/build-package.sh** - Clean package creation with VCS-agnostic support - ✅ **Package structure validation** - Excludes dev files, includes production essentials - ✅ **Version detection** - Auto-detection from VERSION file or git tags - ✅ **Secure exclusions** - No secrets, logs, or development artifacts in packages **Package Output:** ```bash ./scripts/build-package.sh 0.1.1 # Creates: dist/furt-api-gateway-v0.1.1.tar.gz ``` Upload automation implemented locally (not committed for security) with: Forgejo Generic Package API integration Automatic .env config loading HTTP error handling and user feedback Download instructions generation Ready for walter → tiamat pipeline testing once DAW/furt#75 STARTTLS is resolved. Next: Package build integration into deployment workflow.

michael

2025-09-03 20:29:07 +02:00