Compare commits
2 Commits
b0362dc1ca
...
d0fdb2daf6
| Author | SHA1 | Date | |
|---|---|---|---|
|
d0fdb2daf6 | ||
|
|
17d5758421 |
309
VERSIONING.md
Normal file
309
VERSIONING.md
Normal file
@@ -0,0 +1,309 @@
|
|||||||
|
# Wild Cloud Versioning Strategy
|
||||||
|
|
||||||
|
## Current Implementation: Unified Versioning
|
||||||
|
|
||||||
|
Wild Cloud uses a **single source of truth** for versioning during the development phase (pre-v1.0.0). All components (API, CLI, Web, Package) share the same version number.
|
||||||
|
|
||||||
|
### Version File Location
|
||||||
|
```
|
||||||
|
wild-cloud/VERSION
|
||||||
|
```
|
||||||
|
|
||||||
|
Single line file containing the current version (e.g., `0.1.1`).
|
||||||
|
|
||||||
|
### Why Unified Versioning Now?
|
||||||
|
|
||||||
|
- **Simplicity**: One version to track during development
|
||||||
|
- **Tight Coupling**: Components are developed and released together
|
||||||
|
- **Development Phase**: Pre-1.0.0, breaking changes are expected
|
||||||
|
- **Easy Migration**: Can transition to independent versioning later
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version Format
|
||||||
|
|
||||||
|
We follow [Semantic Versioning 2.0.0](https://semver.org/):
|
||||||
|
|
||||||
|
```
|
||||||
|
MAJOR.MINOR.PATCH
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pre-1.0 Semantics (Current)
|
||||||
|
- **MAJOR** (0): Signals development phase
|
||||||
|
- **MINOR** (0.x): New features, may include breaking changes
|
||||||
|
- **PATCH** (0.1.x): Bug fixes, small improvements
|
||||||
|
|
||||||
|
### Post-1.0 Semantics (Future)
|
||||||
|
- **MAJOR**: Breaking changes, incompatible API changes
|
||||||
|
- **MINOR**: New features, backward compatible
|
||||||
|
- **PATCH**: Bug fixes only
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflows
|
||||||
|
|
||||||
|
### Development Workflow (Iterating on Same Version)
|
||||||
|
|
||||||
|
During testing and iteration, update packages without bumping version:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Make code changes
|
||||||
|
cd dist
|
||||||
|
make package-all
|
||||||
|
|
||||||
|
# Update existing release (keeps same version)
|
||||||
|
make release
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result**: Existing release assets are replaced with new builds.
|
||||||
|
|
||||||
|
### Creating a New Release
|
||||||
|
|
||||||
|
When ready for a new version:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Option 1: Use helper script
|
||||||
|
./scripts/bump-version.sh 0.1.2
|
||||||
|
|
||||||
|
# Option 2: Manual steps
|
||||||
|
echo "0.1.2" > VERSION
|
||||||
|
git add VERSION
|
||||||
|
git commit -m "Bump version to 0.1.2"
|
||||||
|
git tag -a v0.1.2 -m "Wild Cloud Central v0.1.2"
|
||||||
|
|
||||||
|
# Build and release
|
||||||
|
cd dist
|
||||||
|
make package-all
|
||||||
|
make release
|
||||||
|
|
||||||
|
# Push to remote
|
||||||
|
cd ..
|
||||||
|
git push origin main v0.1.2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result**: New release with tag `v0.1.2` is created.
|
||||||
|
|
||||||
|
### Quick Reference
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check current version
|
||||||
|
cat VERSION
|
||||||
|
|
||||||
|
# Bump version (helper script)
|
||||||
|
./scripts/bump-version.sh 0.2.0
|
||||||
|
|
||||||
|
# Build packages
|
||||||
|
cd dist && make package-all
|
||||||
|
|
||||||
|
# Create/update release
|
||||||
|
cd dist && make release
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Release Behavior
|
||||||
|
|
||||||
|
The `make release` command is intelligent:
|
||||||
|
|
||||||
|
- **If release v0.1.1 exists**: Updates package assets only
|
||||||
|
- Deletes old .deb files
|
||||||
|
- Uploads new .deb files
|
||||||
|
- Keeps release notes and metadata
|
||||||
|
|
||||||
|
- **If release v0.1.1 doesn't exist**: Creates new release
|
||||||
|
- Creates Git tag
|
||||||
|
- Creates Gitea/GitHub release
|
||||||
|
- Uploads package assets
|
||||||
|
- Generates release notes
|
||||||
|
|
||||||
|
This allows rapid iteration during testing without creating dozens of releases.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Versioning Best Practices
|
||||||
|
|
||||||
|
### When to Bump MINOR (0.x)
|
||||||
|
- New features added
|
||||||
|
- API endpoints added/changed
|
||||||
|
- Breaking changes (pre-1.0)
|
||||||
|
- Significant improvements
|
||||||
|
|
||||||
|
### When to Bump PATCH (0.1.x)
|
||||||
|
- Bug fixes
|
||||||
|
- Security patches
|
||||||
|
- Performance improvements
|
||||||
|
- Documentation updates
|
||||||
|
- No user-facing changes
|
||||||
|
|
||||||
|
### Pre-release Versions
|
||||||
|
For testing before official release:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
echo "0.2.0-rc.1" > VERSION # Release candidate
|
||||||
|
echo "0.2.0-beta.1" > VERSION # Beta testing
|
||||||
|
echo "0.2.0-alpha.1" > VERSION # Alpha testing
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version Information in Components
|
||||||
|
|
||||||
|
### API (Go)
|
||||||
|
Version injected at build time:
|
||||||
|
```go
|
||||||
|
var Version = "dev" // Injected with -ldflags
|
||||||
|
```
|
||||||
|
|
||||||
|
Build command in Makefile:
|
||||||
|
```makefile
|
||||||
|
go build -ldflags="-X main.Version=$(VERSION)"
|
||||||
|
```
|
||||||
|
|
||||||
|
### CLI (Go)
|
||||||
|
Same pattern as API:
|
||||||
|
```go
|
||||||
|
var Version = "dev"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Web (React)
|
||||||
|
Version in package.json (can stay at 0.0.0):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": "0.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Version available via API at runtime.
|
||||||
|
|
||||||
|
### Debian Package
|
||||||
|
Version inserted into control file during packaging:
|
||||||
|
```
|
||||||
|
Package: wild-cloud-central
|
||||||
|
Version: 0.1.1
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Future: Independent Component Versioning
|
||||||
|
|
||||||
|
When Wild Cloud matures (around v1.0.0), we may need independent versioning for components. This is documented in:
|
||||||
|
|
||||||
|
```
|
||||||
|
dist/future/independent-versioning.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Migration Triggers
|
||||||
|
- CLI needs independent releases for CI/CD use
|
||||||
|
- API stability requires different versioning from UI
|
||||||
|
- Different release cadences for components
|
||||||
|
- Need to signal breaking API changes independently
|
||||||
|
|
||||||
|
### Migration Path
|
||||||
|
The future design is already documented and can be implemented when needed:
|
||||||
|
1. Create component VERSION files (api/VERSION, cli/VERSION, web/VERSION)
|
||||||
|
2. Create MANIFEST.yaml for compatibility tracking
|
||||||
|
3. Update build scripts to read multiple versions
|
||||||
|
4. Add CLI version checking against API
|
||||||
|
5. Support component-specific releases
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version Discovery
|
||||||
|
|
||||||
|
### For Users
|
||||||
|
```bash
|
||||||
|
# From command line (future)
|
||||||
|
wild --version
|
||||||
|
# Output: Wild CLI v0.1.1 (API v0.1.1)
|
||||||
|
|
||||||
|
# From package
|
||||||
|
dpkg -l wild-cloud-central
|
||||||
|
# Output: ii wild-cloud-central 0.1.1 ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### For Developers
|
||||||
|
```bash
|
||||||
|
# Current version
|
||||||
|
cat VERSION
|
||||||
|
|
||||||
|
# Version in Makefile
|
||||||
|
cd dist && make version
|
||||||
|
|
||||||
|
# Version info in help
|
||||||
|
cd dist && make help
|
||||||
|
```
|
||||||
|
|
||||||
|
### For Automation
|
||||||
|
```bash
|
||||||
|
# Read version programmatically
|
||||||
|
VERSION=$(cat VERSION)
|
||||||
|
|
||||||
|
# Validate version format
|
||||||
|
if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||||
|
echo "Valid version: $VERSION"
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tools and Scripts
|
||||||
|
|
||||||
|
### Helper Scripts
|
||||||
|
|
||||||
|
**`scripts/bump-version.sh`**
|
||||||
|
- Validates version format
|
||||||
|
- Updates VERSION file
|
||||||
|
- Creates git commit and tag
|
||||||
|
- Provides next steps
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./scripts/bump-version.sh 0.2.0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Makefile Targets
|
||||||
|
|
||||||
|
**`make version`** - Show current version and build info
|
||||||
|
**`make help`** - Shows version management instructions
|
||||||
|
**`make package-all`** - Build packages with current version
|
||||||
|
**`make release`** - Create/update release with current version
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## FAQ
|
||||||
|
|
||||||
|
### Q: Can I release without bumping the version?
|
||||||
|
**A**: Yes! `make release` will update the existing release assets. Perfect for testing.
|
||||||
|
|
||||||
|
### Q: How do I create a patch release?
|
||||||
|
**A**: Bump the PATCH number: `echo "0.1.2" > VERSION`
|
||||||
|
|
||||||
|
### Q: What about pre-release versions?
|
||||||
|
**A**: Use semver pre-release format: `0.2.0-rc.1`, `0.2.0-beta.1`
|
||||||
|
|
||||||
|
### Q: When should we switch to independent versioning?
|
||||||
|
**A**: When CLI needs separate releases or API needs stability guarantees (likely around v1.0.0)
|
||||||
|
|
||||||
|
### Q: Can I manually edit the VERSION file?
|
||||||
|
**A**: Yes! It's just a text file. Or use `./scripts/bump-version.sh` for automation.
|
||||||
|
|
||||||
|
### Q: How does this work with git tags?
|
||||||
|
**A**: Git tags follow the version: `v0.1.1`. Create them manually or use the bump script.
|
||||||
|
|
||||||
|
### Q: What if I forget to bump the version?
|
||||||
|
**A**: No problem! The release will update the existing version's assets.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Semantic Versioning 2.0.0](https://semver.org/)
|
||||||
|
- [Keep a Changelog](https://keepachangelog.com/)
|
||||||
|
- Future design: `dist/future/independent-versioning.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
**Current State**: Single VERSION file, unified versioning, perfect for development
|
||||||
|
**Future State**: Independent component versioning when needed (documented in future/)
|
||||||
|
**Philosophy**: Keep it simple until complexity is justified
|
||||||
6
dist/CLAUDE.md
vendored
Normal file
6
dist/CLAUDE.md
vendored
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
This directory `dist` contains tooling for building Wild Central distributions.
|
||||||
|
|
||||||
|
`make package-all` will check out the latest source for the api, web, and cli build them, and build apt packages in arm64 and amd64. These files are then manually copied to github releases.
|
||||||
|
|
||||||
|
- @README.md
|
||||||
|
|
||||||
153
dist/Makefile
vendored
153
dist/Makefile
vendored
@@ -2,7 +2,7 @@
|
|||||||
.DEFAULT_GOAL := help
|
.DEFAULT_GOAL := help
|
||||||
|
|
||||||
# Build configuration
|
# Build configuration
|
||||||
VERSION ?= 0.1.1
|
VERSION := $(shell cat ../VERSION 2>/dev/null || echo "0.0.0-dev")
|
||||||
BUILD_DIR := build
|
BUILD_DIR := build
|
||||||
DIST_DIR := dist
|
DIST_DIR := dist
|
||||||
DEB_DIR := debian-package
|
DEB_DIR := debian-package
|
||||||
@@ -11,7 +11,24 @@ DEB_DIR := debian-package
|
|||||||
GIT_COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
|
GIT_COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
|
||||||
BUILD_TIME := $(shell date -u '+%Y-%m-%d_%H:%M:%S')
|
BUILD_TIME := $(shell date -u '+%Y-%m-%d_%H:%M:%S')
|
||||||
|
|
||||||
.PHONY: help build clean package repo deploy-repo build-arm64 build-amd64 package-arm64 package-amd64 package-all version
|
# Source paths
|
||||||
|
API_SOURCE := ../api
|
||||||
|
WEB_SOURCE := ../web
|
||||||
|
|
||||||
|
# Output files
|
||||||
|
ARM64_BINARY := $(BUILD_DIR)/wild-cloud-central-arm64
|
||||||
|
AMD64_BINARY := $(BUILD_DIR)/wild-cloud-central-amd64
|
||||||
|
WEB_DIST_MARKER := $(BUILD_DIR)/.web-built
|
||||||
|
ARM64_DEB := $(DIST_DIR)/packages/wild-cloud-central_$(VERSION)_arm64.deb
|
||||||
|
AMD64_DEB := $(DIST_DIR)/packages/wild-cloud-central_$(VERSION)_amd64.deb
|
||||||
|
|
||||||
|
# Gitea release configuration
|
||||||
|
GITEA_URL := https://git.civilsociety.dev
|
||||||
|
GITEA_OWNER := wild-cloud
|
||||||
|
GITEA_REPO := wild-cloud
|
||||||
|
RELEASE_TAG := v$(VERSION)
|
||||||
|
|
||||||
|
.PHONY: help clean version build build-all package package-all repo deploy-repo release
|
||||||
|
|
||||||
help:
|
help:
|
||||||
@echo "📦 Wild Cloud Central Package Builder"
|
@echo "📦 Wild Cloud Central Package Builder"
|
||||||
@@ -23,105 +40,97 @@ help:
|
|||||||
@echo ""
|
@echo ""
|
||||||
@echo "📦 Build targets:"
|
@echo "📦 Build targets:"
|
||||||
@echo " build - Build for current architecture (amd64)"
|
@echo " build - Build for current architecture (amd64)"
|
||||||
@echo " build-arm64 - Build arm64 binary and web app"
|
|
||||||
@echo " build-amd64 - Build amd64 binary and web app"
|
|
||||||
@echo " build-all - Build all architectures"
|
@echo " build-all - Build all architectures"
|
||||||
@echo ""
|
@echo ""
|
||||||
@echo "📋 Package targets:"
|
@echo "📋 Package targets:"
|
||||||
@echo " package - Create .deb package (amd64)"
|
@echo " package - Create .deb package (amd64)"
|
||||||
@echo " package-arm64 - Create arm64 .deb package"
|
|
||||||
@echo " package-amd64 - Create amd64 .deb package"
|
|
||||||
@echo " package-all - Create all .deb packages"
|
@echo " package-all - Create all .deb packages"
|
||||||
@echo ""
|
@echo ""
|
||||||
@echo "🚀 Repository targets:"
|
@echo "🚀 Repository targets:"
|
||||||
@echo " repo - Build APT repository from packages"
|
@echo " repo - Build APT repository from packages"
|
||||||
@echo " deploy-repo - Deploy repository to server"
|
@echo " deploy-repo - Deploy repository to server"
|
||||||
@echo ""
|
@echo ""
|
||||||
|
@echo "🎯 Release targets:"
|
||||||
|
@echo " release - Create/update Gitea release with packages"
|
||||||
|
@echo ""
|
||||||
@echo "🛠️ Utilities:"
|
@echo "🛠️ Utilities:"
|
||||||
@echo " clean - Remove all build artifacts"
|
@echo " clean - Remove all build artifacts"
|
||||||
@echo " version - Show build information"
|
@echo " version - Show build information"
|
||||||
@echo ""
|
@echo ""
|
||||||
|
@echo "Version Management:"
|
||||||
|
@echo " Current version: $(VERSION) (from ../VERSION)"
|
||||||
|
@echo " To bump version: echo '0.1.2' > ../VERSION"
|
||||||
|
@echo ""
|
||||||
@echo "Environment variables:"
|
@echo "Environment variables:"
|
||||||
@echo " VERSION - Package version (default: 0.1.1)"
|
@echo " GITEA_TOKEN - Gitea API token (required for release)"
|
||||||
|
@echo " Run: source .envrc"
|
||||||
# Function to create debian package for specific architecture
|
|
||||||
define package_deb
|
|
||||||
@echo "📦 Creating .deb package for $(1)..."
|
|
||||||
@mkdir -p $(DIST_DIR)/bin $(DIST_DIR)/packages
|
|
||||||
|
|
||||||
@# Copy debian package structure
|
|
||||||
@cp -r debian/ $(BUILD_DIR)/$(DEB_DIR)-$(1)/
|
|
||||||
|
|
||||||
@# Copy binary to correct location
|
|
||||||
@mkdir -p $(BUILD_DIR)/$(DEB_DIR)-$(1)/usr/bin
|
|
||||||
@cp $(BUILD_DIR)/$(2) $(BUILD_DIR)/$(DEB_DIR)-$(1)/usr/bin/wild-cloud-central
|
|
||||||
|
|
||||||
@# Copy static web files from built web app
|
|
||||||
@mkdir -p $(BUILD_DIR)/$(DEB_DIR)-$(1)/var/www/html/wild-central
|
|
||||||
@if [ -d "$(BUILD_DIR)/src/web/dist" ]; then \
|
|
||||||
cp -r $(BUILD_DIR)/src/web/dist/* $(BUILD_DIR)/$(DEB_DIR)-$(1)/var/www/html/wild-central/; \
|
|
||||||
echo "✅ Copied web app files"; \
|
|
||||||
else \
|
|
||||||
echo "⚠️ Warning: Web app dist not found at $(BUILD_DIR)/src/web/dist"; \
|
|
||||||
fi
|
|
||||||
|
|
||||||
@# Set script permissions
|
|
||||||
@chmod 755 $(BUILD_DIR)/$(DEB_DIR)-$(1)/DEBIAN/postinst
|
|
||||||
@chmod 755 $(BUILD_DIR)/$(DEB_DIR)-$(1)/DEBIAN/prerm
|
|
||||||
@chmod 755 $(BUILD_DIR)/$(DEB_DIR)-$(1)/DEBIAN/postrm
|
|
||||||
|
|
||||||
@# Substitute placeholders in control file
|
|
||||||
@sed -i 's/VERSION_PLACEHOLDER/$(VERSION)/g' $(BUILD_DIR)/$(DEB_DIR)-$(1)/DEBIAN/control
|
|
||||||
@sed -i 's/ARCH_PLACEHOLDER/$(1)/g' $(BUILD_DIR)/$(DEB_DIR)-$(1)/DEBIAN/control
|
|
||||||
|
|
||||||
@# Build package and copy to dist directories
|
|
||||||
dpkg-deb --build $(BUILD_DIR)/$(DEB_DIR)-$(1) $(BUILD_DIR)/wild-cloud-central_$(VERSION)_$(1).deb
|
|
||||||
@cp $(BUILD_DIR)/$(2) $(DIST_DIR)/bin/wild-cloud-central-$(1)
|
|
||||||
@cp $(BUILD_DIR)/wild-cloud-central_$(VERSION)_$(1).deb $(DIST_DIR)/packages/
|
|
||||||
@echo "✅ Package created: $(DIST_DIR)/packages/wild-cloud-central_$(VERSION)_$(1).deb"
|
|
||||||
@echo "✅ Binary copied: $(DIST_DIR)/bin/wild-cloud-central-$(1)"
|
|
||||||
endef
|
|
||||||
|
|
||||||
build: build-amd64
|
|
||||||
|
|
||||||
build-arm64:
|
|
||||||
@echo "Building for arm64..."
|
|
||||||
@ARCH=arm64 VERSION=$(VERSION) ./scripts/build-package.sh
|
|
||||||
@mv $(BUILD_DIR)/bin/wild-cloud-central $(BUILD_DIR)/wild-cloud-central-arm64
|
|
||||||
@echo "✅ Build complete: $(BUILD_DIR)/wild-cloud-central-arm64"
|
|
||||||
|
|
||||||
build-amd64:
|
|
||||||
@echo "Building for amd64..."
|
|
||||||
@ARCH=amd64 VERSION=$(VERSION) ./scripts/build-package.sh
|
|
||||||
@mv $(BUILD_DIR)/bin/wild-cloud-central $(BUILD_DIR)/wild-cloud-central-amd64
|
|
||||||
@echo "✅ Build complete: $(BUILD_DIR)/wild-cloud-central-amd64"
|
|
||||||
|
|
||||||
build-all: build-arm64 build-amd64
|
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
@echo "🧹 Cleaning build artifacts..."
|
@echo "🧹 Cleaning build artifacts..."
|
||||||
@rm -rf $(BUILD_DIR) $(DIST_DIR) $(DEB_DIR)-* $(DEB_DIR)
|
@rm -rf $(BUILD_DIR) $(DIST_DIR) $(DEB_DIR)-* $(DEB_DIR)
|
||||||
@echo "✅ Clean complete"
|
@echo "✅ Clean complete"
|
||||||
|
|
||||||
# Version information
|
|
||||||
version:
|
version:
|
||||||
@echo "Version: $(VERSION)"
|
@echo "Version: $(VERSION)"
|
||||||
@echo "Git Commit: $(GIT_COMMIT)"
|
@echo "Git Commit: $(GIT_COMMIT)"
|
||||||
@echo "Build Time: $(BUILD_TIME)"
|
@echo "Build Time: $(BUILD_TIME)"
|
||||||
|
|
||||||
# Package targets - create .deb packages
|
# Web app build - track with marker file
|
||||||
package-arm64: build-arm64
|
$(WEB_DIST_MARKER): $(shell find $(WEB_SOURCE)/src -type f 2>/dev/null | head -100) $(WEB_SOURCE)/package.json
|
||||||
$(call package_deb,arm64,wild-cloud-central-arm64)
|
@echo "🔧 Building web application..."
|
||||||
|
@ARCH=amd64 VERSION=$(VERSION) ./scripts/build-package.sh
|
||||||
|
@touch $(WEB_DIST_MARKER)
|
||||||
|
@echo "✅ Web app built"
|
||||||
|
|
||||||
package-amd64: build-amd64
|
# ARM64 binary
|
||||||
$(call package_deb,amd64,wild-cloud-central-amd64)
|
$(ARM64_BINARY): $(shell find $(API_SOURCE) -name '*.go' 2>/dev/null | head -100)
|
||||||
|
@echo "🔧 Building arm64 binary..."
|
||||||
|
@mkdir -p $(BUILD_DIR)/bin
|
||||||
|
@cd $(API_SOURCE) && GOOS=linux GOARCH=arm64 go build -ldflags="-X main.Version=$(VERSION)" -o ../dist/$(ARM64_BINARY) .
|
||||||
|
@echo "✅ Build complete: $(ARM64_BINARY)"
|
||||||
|
|
||||||
package-all: package-arm64 package-amd64
|
# AMD64 binary
|
||||||
|
$(AMD64_BINARY): $(shell find $(API_SOURCE) -name '*.go' 2>/dev/null | head -100)
|
||||||
|
@echo "🔧 Building amd64 binary..."
|
||||||
|
@mkdir -p $(BUILD_DIR)/bin
|
||||||
|
@cd $(API_SOURCE) && GOOS=linux GOARCH=amd64 go build -ldflags="-X main.Version=$(VERSION)" -o ../dist/$(AMD64_BINARY) .
|
||||||
|
@echo "✅ Build complete: $(AMD64_BINARY)"
|
||||||
|
|
||||||
package: package-amd64
|
# ARM64 package
|
||||||
|
$(ARM64_DEB): $(ARM64_BINARY) $(WEB_DIST_MARKER)
|
||||||
|
@echo "📦 Creating arm64 .deb package..."
|
||||||
|
@./scripts/package-deb.sh arm64 $(ARM64_BINARY) $(VERSION)
|
||||||
|
@echo "✅ Package created: $(ARM64_DEB)"
|
||||||
|
|
||||||
repo: package-all
|
# AMD64 package
|
||||||
./scripts/build-apt-repository.sh
|
$(AMD64_DEB): $(AMD64_BINARY) $(WEB_DIST_MARKER)
|
||||||
|
@echo "📦 Creating amd64 .deb package..."
|
||||||
|
@./scripts/package-deb.sh amd64 $(AMD64_BINARY) $(VERSION)
|
||||||
|
@echo "✅ Package created: $(AMD64_DEB)"
|
||||||
|
|
||||||
|
# Convenience targets
|
||||||
|
build: $(AMD64_BINARY) $(WEB_DIST_MARKER)
|
||||||
|
|
||||||
|
build-all: $(ARM64_BINARY) $(AMD64_BINARY) $(WEB_DIST_MARKER)
|
||||||
|
|
||||||
|
package: $(AMD64_DEB)
|
||||||
|
|
||||||
|
package-all: $(ARM64_DEB) $(AMD64_DEB)
|
||||||
|
|
||||||
|
repo: $(ARM64_DEB) $(AMD64_DEB)
|
||||||
|
@echo "🏗️ Building APT repository..."
|
||||||
|
@./scripts/build-apt-repository.sh
|
||||||
|
|
||||||
deploy-repo: repo
|
deploy-repo: repo
|
||||||
./scripts/deploy-apt-repository.sh
|
@echo "🚀 Deploying APT repository..."
|
||||||
|
@./scripts/deploy-apt-repository.sh
|
||||||
|
|
||||||
|
release: $(ARM64_DEB) $(AMD64_DEB)
|
||||||
|
@echo "🎯 Creating release $(RELEASE_TAG)..."
|
||||||
|
@if [ -z "$(GITEA_TOKEN)" ]; then \
|
||||||
|
echo "❌ Error: GITEA_TOKEN environment variable not set"; \
|
||||||
|
echo " Get a token from $(GITEA_URL)/user/settings/applications"; \
|
||||||
|
echo " Or run: source .envrc"; \
|
||||||
|
exit 1; \
|
||||||
|
fi
|
||||||
|
@./scripts/create-gitea-release.sh "$(GITEA_URL)" "$(GITEA_OWNER)" "$(GITEA_REPO)" "$(RELEASE_TAG)" "$(VERSION)" "$(GITEA_TOKEN)"
|
||||||
|
|||||||
107
dist/README.md
vendored
107
dist/README.md
vendored
@@ -1,32 +1,8 @@
|
|||||||
# Packaging Wild Central
|
# Packaging Wild Central
|
||||||
|
|
||||||
## Desired Experience
|
## Installation
|
||||||
|
|
||||||
This is the desired experience for installing Wild Cloud Central on a fresh Debian/Ubuntu system:
|
Download the latest `.deb` package from the [releases page](https://git.civilsociety.dev/wild-cloud/wild-cloud/releases) and install:
|
||||||
|
|
||||||
### APT Repository (Recommended)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Download and install GPG key
|
|
||||||
curl -fsSL https://mywildcloud.org/apt/wild-cloud-central.gpg | sudo tee /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg > /dev/null
|
|
||||||
|
|
||||||
# Add repository (modern .sources format)
|
|
||||||
sudo tee /etc/apt/sources.list.d/wild-cloud-central.sources << 'EOF'
|
|
||||||
Types: deb
|
|
||||||
URIs: https://mywildcloud.org/apt
|
|
||||||
Suites: stable
|
|
||||||
Components: main
|
|
||||||
Signed-By: /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# Update and install
|
|
||||||
sudo apt update
|
|
||||||
sudo apt install wild-cloud-central
|
|
||||||
```
|
|
||||||
|
|
||||||
### Manual Installation
|
|
||||||
|
|
||||||
Download the latest `.deb` package from the [releases page](https://github.com/wildcloud/wild-central/releases) and install:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo dpkg -i wild-cloud-central_*.deb
|
sudo dpkg -i wild-cloud-central_*.deb
|
||||||
@@ -52,6 +28,61 @@ sudo apt-get install -f # Fix any dependency issues
|
|||||||
3. **Access the web interface**:
|
3. **Access the web interface**:
|
||||||
Open http://your-server-ip in your browser
|
Open http://your-server-ip in your browser
|
||||||
|
|
||||||
|
## Version Management
|
||||||
|
|
||||||
|
Wild Cloud uses a single VERSION file at the monorepo root (`wild-cloud/VERSION`) that tracks the unified version for all components (API, CLI, Web, and the package itself).
|
||||||
|
|
||||||
|
### Current Version
|
||||||
|
```bash
|
||||||
|
cat ../VERSION # Shows current version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Development Workflow (Testing Phase)
|
||||||
|
|
||||||
|
During development, iterate on the same version:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Make changes to code
|
||||||
|
make package-all
|
||||||
|
|
||||||
|
# Update existing release (no version bump)
|
||||||
|
make release # Updates assets in current release
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creating a New Release
|
||||||
|
|
||||||
|
When ready for a new release:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Bump version
|
||||||
|
echo "0.1.2" > ../VERSION
|
||||||
|
|
||||||
|
# 2. Build packages
|
||||||
|
make package-all
|
||||||
|
|
||||||
|
# 3. Create new release
|
||||||
|
make release # Creates v0.1.2 tag and release
|
||||||
|
|
||||||
|
# 4. Commit and tag
|
||||||
|
cd ..
|
||||||
|
git add VERSION
|
||||||
|
git commit -m "Bump version to 0.1.2"
|
||||||
|
git tag -a v0.1.2 -m "Wild Cloud Central v0.1.2"
|
||||||
|
git push origin main v0.1.2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Release Behavior
|
||||||
|
|
||||||
|
The `make release` command automatically:
|
||||||
|
- **If release exists**: Updates package assets only (deletes old .deb files, uploads new ones)
|
||||||
|
- **If release doesn't exist**: Creates new release with packages
|
||||||
|
|
||||||
|
This allows iterating during testing without creating multiple releases.
|
||||||
|
|
||||||
|
### Future: Independent Component Versioning
|
||||||
|
|
||||||
|
For future enhancement when components need independent versions, see `future/independent-versioning.md`.
|
||||||
|
|
||||||
## Developer tooling
|
## Developer tooling
|
||||||
|
|
||||||
Makefile commands for packaging:
|
Makefile commands for packaging:
|
||||||
@@ -77,3 +108,27 @@ dist/repositories/ - APT repository for deployment
|
|||||||
|
|
||||||
Example workflows:
|
Example workflows:
|
||||||
make clean && make repo - Full release build
|
make clean && make repo - Full release build
|
||||||
|
|
||||||
|
## Future packaging
|
||||||
|
|
||||||
|
We'll be putting the packages in a proper repository in the future for installing Wild Cloud Central on a fresh Debian/Ubuntu system:
|
||||||
|
|
||||||
|
### APT Repository (TBD)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Download and install GPG key
|
||||||
|
curl -fsSL https://mywildcloud.org/apt/wild-cloud-central.gpg | sudo tee /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg > /dev/null
|
||||||
|
|
||||||
|
# Add repository (modern .sources format)
|
||||||
|
sudo tee /etc/apt/sources.list.d/wild-cloud-central.sources << 'EOF'
|
||||||
|
Types: deb
|
||||||
|
URIs: https://mywildcloud.org/apt
|
||||||
|
Suites: stable
|
||||||
|
Components: main
|
||||||
|
Signed-By: /usr/share/keyrings/wild-cloud-central-archive-keyring.gpg
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Update and install
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install wild-cloud-central
|
||||||
|
```
|
||||||
|
|||||||
112
dist/scripts/create-gitea-release.sh
vendored
Executable file
112
dist/scripts/create-gitea-release.sh
vendored
Executable file
@@ -0,0 +1,112 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
GITEA_URL="$1"
|
||||||
|
OWNER="$2"
|
||||||
|
REPO="$3"
|
||||||
|
TAG="$4"
|
||||||
|
VERSION="$5"
|
||||||
|
TOKEN="$6"
|
||||||
|
|
||||||
|
API_URL="${GITEA_URL}/api/v1"
|
||||||
|
DIST_DIR="dist/packages"
|
||||||
|
|
||||||
|
echo "📦 Release configuration:"
|
||||||
|
echo " Repository: ${OWNER}/${REPO}"
|
||||||
|
echo " Tag: ${TAG}"
|
||||||
|
echo " Version: ${VERSION}"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check if release already exists
|
||||||
|
echo "🔍 Checking if release ${TAG} exists..."
|
||||||
|
RELEASE_ID=$(curl -s -H "Authorization: token ${TOKEN}" \
|
||||||
|
"${API_URL}/repos/${OWNER}/${REPO}/releases/tags/${TAG}" \
|
||||||
|
| jq -r '.id // empty')
|
||||||
|
|
||||||
|
if [ -n "$RELEASE_ID" ]; then
|
||||||
|
echo "✅ Release ${TAG} exists (ID: ${RELEASE_ID})"
|
||||||
|
echo "📦 Updating existing release assets..."
|
||||||
|
|
||||||
|
# Get existing assets
|
||||||
|
EXISTING_ASSETS=$(curl -s -H "Authorization: token ${TOKEN}" \
|
||||||
|
"${API_URL}/repos/${OWNER}/${REPO}/releases/${RELEASE_ID}/assets" \
|
||||||
|
| jq -r '.[].id')
|
||||||
|
|
||||||
|
# Delete old .deb assets
|
||||||
|
for ASSET_ID in $EXISTING_ASSETS; do
|
||||||
|
ASSET_NAME=$(curl -s -H "Authorization: token ${TOKEN}" \
|
||||||
|
"${API_URL}/repos/${OWNER}/${REPO}/releases/assets/${ASSET_ID}" \
|
||||||
|
| jq -r '.name')
|
||||||
|
|
||||||
|
if [[ "$ASSET_NAME" == *.deb ]]; then
|
||||||
|
echo " Deleting old asset: ${ASSET_NAME}"
|
||||||
|
curl -s -X DELETE -H "Authorization: token ${TOKEN}" \
|
||||||
|
"${API_URL}/repos/${OWNER}/${REPO}/releases/assets/${ASSET_ID}"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
echo "✅ Cleaned up old package assets"
|
||||||
|
SKIP_RELEASE_CREATION=true
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Create new release if it doesn't exist
|
||||||
|
if [ "$SKIP_RELEASE_CREATION" != "true" ]; then
|
||||||
|
echo "📝 Creating new release ${TAG}..."
|
||||||
|
RELEASE_DATA=$(cat <<EOF
|
||||||
|
{
|
||||||
|
"tag_name": "${TAG}",
|
||||||
|
"name": "Wild Cloud Central ${VERSION}",
|
||||||
|
"body": "## Wild Cloud Central ${VERSION}\n\n### Installation\n\nDownload the appropriate .deb package for your architecture:\n\n- **arm64**: For Raspberry Pi 4/5, ARM-based servers\n- **amd64**: For x86_64 systems\n\n\`\`\`bash\n# Install package\nsudo dpkg -i wild-cloud-central_${VERSION}_<arch>.deb\nsudo apt-get install -f\n\n# Start service\nsudo systemctl enable wild-cloud-central\nsudo systemctl start wild-cloud-central\n\`\`\`\n\n### What's Included\n\n- Wild Cloud Central API daemon\n- Web-based management interface\n- CLI tools\n- systemd service configuration",
|
||||||
|
"draft": false,
|
||||||
|
"prerelease": false
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
|
||||||
|
RELEASE_RESPONSE=$(curl -s -X POST -H "Authorization: token ${TOKEN}" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "${RELEASE_DATA}" \
|
||||||
|
"${API_URL}/repos/${OWNER}/${REPO}/releases")
|
||||||
|
|
||||||
|
RELEASE_ID=$(echo "${RELEASE_RESPONSE}" | jq -r '.id')
|
||||||
|
|
||||||
|
if [ -z "$RELEASE_ID" ] || [ "$RELEASE_ID" = "null" ]; then
|
||||||
|
echo "❌ Failed to create release"
|
||||||
|
echo "${RELEASE_RESPONSE}" | jq .
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✅ Created release ${TAG} (ID: ${RELEASE_ID})"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Upload packages
|
||||||
|
echo ""
|
||||||
|
echo "📤 Uploading packages..."
|
||||||
|
|
||||||
|
for DEB in ${DIST_DIR}/*.deb; do
|
||||||
|
if [ ! -f "$DEB" ]; then
|
||||||
|
echo "⚠️ No .deb files found in ${DIST_DIR}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
FILENAME=$(basename "$DEB")
|
||||||
|
echo " Uploading ${FILENAME}..."
|
||||||
|
|
||||||
|
UPLOAD_RESPONSE=$(curl -s -X POST \
|
||||||
|
-H "Authorization: token ${TOKEN}" \
|
||||||
|
-F "attachment=@${DEB}" \
|
||||||
|
"${API_URL}/repos/${OWNER}/${REPO}/releases/${RELEASE_ID}/assets?name=${FILENAME}")
|
||||||
|
|
||||||
|
ASSET_ID=$(echo "${UPLOAD_RESPONSE}" | jq -r '.id')
|
||||||
|
|
||||||
|
if [ -z "$ASSET_ID" ] || [ "$ASSET_ID" = "null" ]; then
|
||||||
|
echo " ❌ Failed to upload ${FILENAME}"
|
||||||
|
echo "${UPLOAD_RESPONSE}" | jq .
|
||||||
|
else
|
||||||
|
echo " ✅ Uploaded ${FILENAME} (Asset ID: ${ASSET_ID})"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "✨ Release complete!"
|
||||||
|
echo "🔗 View at: ${GITEA_URL}/${OWNER}/${REPO}/releases/tag/${TAG}"
|
||||||
49
dist/scripts/package-deb.sh
vendored
Executable file
49
dist/scripts/package-deb.sh
vendored
Executable file
@@ -0,0 +1,49 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
ARCH="$1"
|
||||||
|
BINARY_PATH="$2"
|
||||||
|
VERSION="$3"
|
||||||
|
|
||||||
|
BUILD_DIR="build"
|
||||||
|
DIST_DIR="dist"
|
||||||
|
DEB_DIR="debian-package"
|
||||||
|
WEB_DIST="${BUILD_DIR}/src/web/dist"
|
||||||
|
|
||||||
|
echo "📦 Creating .deb package for ${ARCH}..."
|
||||||
|
|
||||||
|
# Create directories
|
||||||
|
mkdir -p "${DIST_DIR}/bin" "${DIST_DIR}/packages"
|
||||||
|
|
||||||
|
# Copy debian package structure
|
||||||
|
cp -r debian/ "${BUILD_DIR}/${DEB_DIR}-${ARCH}/"
|
||||||
|
|
||||||
|
# Copy binary to correct location
|
||||||
|
mkdir -p "${BUILD_DIR}/${DEB_DIR}-${ARCH}/usr/bin"
|
||||||
|
cp "${BINARY_PATH}" "${BUILD_DIR}/${DEB_DIR}-${ARCH}/usr/bin/wild-cloud-central"
|
||||||
|
|
||||||
|
# Copy static web files from built web app
|
||||||
|
mkdir -p "${BUILD_DIR}/${DEB_DIR}-${ARCH}/var/www/html/wild-central"
|
||||||
|
if [ -d "${WEB_DIST}" ]; then
|
||||||
|
cp -r "${WEB_DIST}"/* "${BUILD_DIR}/${DEB_DIR}-${ARCH}/var/www/html/wild-central/"
|
||||||
|
echo "✅ Copied web app files"
|
||||||
|
else
|
||||||
|
echo "⚠️ Warning: Web app dist not found at ${WEB_DIST}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Set script permissions
|
||||||
|
chmod 755 "${BUILD_DIR}/${DEB_DIR}-${ARCH}/DEBIAN/postinst"
|
||||||
|
chmod 755 "${BUILD_DIR}/${DEB_DIR}-${ARCH}/DEBIAN/prerm"
|
||||||
|
chmod 755 "${BUILD_DIR}/${DEB_DIR}-${ARCH}/DEBIAN/postrm"
|
||||||
|
|
||||||
|
# Substitute placeholders in control file
|
||||||
|
sed -i "s/VERSION_PLACEHOLDER/${VERSION}/g" "${BUILD_DIR}/${DEB_DIR}-${ARCH}/DEBIAN/control"
|
||||||
|
sed -i "s/ARCH_PLACEHOLDER/${ARCH}/g" "${BUILD_DIR}/${DEB_DIR}-${ARCH}/DEBIAN/control"
|
||||||
|
|
||||||
|
# Build package and copy to dist directories
|
||||||
|
dpkg-deb --build "${BUILD_DIR}/${DEB_DIR}-${ARCH}" "${BUILD_DIR}/wild-cloud-central_${VERSION}_${ARCH}.deb"
|
||||||
|
cp "${BINARY_PATH}" "${DIST_DIR}/bin/wild-cloud-central-${ARCH}"
|
||||||
|
cp "${BUILD_DIR}/wild-cloud-central_${VERSION}_${ARCH}.deb" "${DIST_DIR}/packages/"
|
||||||
|
|
||||||
|
echo "✅ Package created: ${DIST_DIR}/packages/wild-cloud-central_${VERSION}_${ARCH}.deb"
|
||||||
|
echo "✅ Binary copied: ${DIST_DIR}/bin/wild-cloud-central-${ARCH}"
|
||||||
61
scripts/bump-version.sh
Executable file
61
scripts/bump-version.sh
Executable file
@@ -0,0 +1,61 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
NEW_VERSION="$1"
|
||||||
|
|
||||||
|
if [ -z "$NEW_VERSION" ]; then
|
||||||
|
echo "Usage: $0 <new-version>"
|
||||||
|
echo "Example: $0 0.1.2"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Validate version format (basic check)
|
||||||
|
if ! [[ "$NEW_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
|
||||||
|
echo "Error: Invalid version format. Use: MAJOR.MINOR.PATCH or MAJOR.MINOR.PATCH-prerelease"
|
||||||
|
echo "Examples: 0.1.2, 0.2.0, 1.0.0, 0.1.2-rc.1"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||||
|
VERSION_FILE="$REPO_ROOT/VERSION"
|
||||||
|
|
||||||
|
CURRENT_VERSION=$(cat "$VERSION_FILE" 2>/dev/null || echo "unknown")
|
||||||
|
|
||||||
|
echo "Bumping version: $CURRENT_VERSION → $NEW_VERSION"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Update VERSION file
|
||||||
|
echo "$NEW_VERSION" > "$VERSION_FILE"
|
||||||
|
echo "✅ Updated $VERSION_FILE"
|
||||||
|
|
||||||
|
# Git operations
|
||||||
|
if git rev-parse --git-dir > /dev/null 2>&1; then
|
||||||
|
echo ""
|
||||||
|
echo "Git operations:"
|
||||||
|
|
||||||
|
# Stage the file
|
||||||
|
git add "$VERSION_FILE"
|
||||||
|
echo "✅ Staged VERSION file"
|
||||||
|
|
||||||
|
# Commit
|
||||||
|
git commit -m "Bump version to $NEW_VERSION"
|
||||||
|
echo "✅ Committed version bump"
|
||||||
|
|
||||||
|
# Create tag
|
||||||
|
git tag -a "v$NEW_VERSION" -m "Wild Cloud Central v$NEW_VERSION"
|
||||||
|
echo "✅ Created tag v$NEW_VERSION"
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "📋 Next steps:"
|
||||||
|
echo " 1. Review the commit: git show"
|
||||||
|
echo " 2. Build packages: cd dist && make package-all"
|
||||||
|
echo " 3. Create release: cd dist && make release"
|
||||||
|
echo " 4. Push to remote: git push origin main v$NEW_VERSION"
|
||||||
|
else
|
||||||
|
echo ""
|
||||||
|
echo "⚠️ Not a git repository, skipping git operations"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "✨ Version bump complete!"
|
||||||
Reference in New Issue
Block a user