gitea-mirror/Pulse
1
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-02-18 00:17:39 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
5a2d808aa16e01de3e1b163f1df3c711005891ce
Pulse/docs/installer-v2-quickref.md
rcourtman 0fcfad3dc5 feat: add shared script library system and refactor docker-agent installer 
Implements a comprehensive script improvement infrastructure to reduce code
duplication, improve maintainability, and enable easier testing of installer
scripts.

## New Infrastructure

### Shared Library System (scripts/lib/)
- common.sh: Core utilities (logging, sudo, dry-run, cleanup management)
- systemd.sh: Service management helpers with container-safe systemctl
- http.sh: HTTP/download helpers with curl/wget fallback and retry logic
- README.md: Complete API documentation for all library functions

### Bundler System
- scripts/bundle.sh: Concatenates library modules into single-file installers
- scripts/bundle.manifest: Defines bundling configuration for distributables
- Enables both modular development and curl|bash distribution

### Test Infrastructure
- scripts/tests/run.sh: Test harness for running all smoke tests
- scripts/tests/test-common-lib.sh: Common library validation (5 tests)
- scripts/tests/test-docker-agent-v2.sh: Installer smoke tests (4 tests)
- scripts/tests/integration/: Container-based integration tests (5 scenarios)
- All tests passing ✓

## Refactored Installer

### install-docker-agent-v2.sh
- Reduced from 1098 to 563 lines (48% code reduction)
- Uses shared libraries for all common operations
- NEW: --dry-run flag support
- Maintains 100% backward compatibility with original
- Fully tested with smoke and integration tests

### Key Improvements
- Sudo escalation: 100+ lines → 1 function call
- Download logic: 51 lines → 1 function call
- Service creation: 33 lines → 2 function calls
- Logging: Standardized across all operations
- Error handling: Improved with common library

## Documentation

### Rollout Strategy (docs/installer-v2-rollout.md)
- 3-phase rollout plan (Alpha → Beta → GA)
- Feature flag mechanism for gradual deployment
- Testing checklist and success metrics
- Rollback procedures and communication plan

### Developer Guides
- docs/script-library-guide.md: Complete library usage guide
- docs/CONTRIBUTING-SCRIPTS.md: Contribution workflow
- docs/installer-v2-quickref.md: Quick reference for operators

## Metrics

- Code reduction: 48% (1098 → 563 lines)
- Reusable functions: 0 → 30+
- Test coverage: 0 → 8 test scenarios
- Documentation: 0 → 5 comprehensive guides

## Testing

All tests passing:
- Smoke tests: 2/2 passed (8 test cases)
- Integration tests: 5/5 scenarios passed
- Bundled output: Syntax validated, dry-run tested

## Next Steps

This lays the foundation for migrating other installers (install.sh,
install-sensor-proxy.sh) to use the same pattern, reducing overall
maintenance burden and improving code quality across the project.
2025-10-20 15:13:38 +00:00

1.8 KiB
Raw Blame History

Installer v2 Quick Reference

Opt-In / Opt-Out

# Use the new installer
export PULSE_INSTALLER_V2=1
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- [flags]

# Force the legacy installer
export PULSE_INSTALLER_V2=0
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- [flags]

Common Flags

  • --url <https://pulse.example> — Primary Pulse server URL
  • --token <api-token> — API token for enrollment
  • --target <url|token[|insecure]> — Additional targets (repeatable)
  • --interval <duration> — Poll interval (default 30s)
  • --dry-run — Show actions without applying changes
  • --uninstall — Remove agent binary, systemd unit, and startup hooks

Examples

# Preview installation without changes
export PULSE_INSTALLER_V2=1
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- \
  --dry-run \
  --url https://pulse.example \
  --token <api-token>

# Install with two targets and custom interval
export PULSE_INSTALLER_V2=1
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- \
  --url https://pulse-primary \
  --token <api-token> \
  --target https://pulse-dr|<dr-token> \
  --target https://pulse-edge|<edge-token>|true \
  --interval 15s

# Uninstall
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- --uninstall

Verification

  • Binary path: /usr/local/bin/pulse-docker-agent
  • Systemd unit: /etc/systemd/system/pulse-docker-agent.service
  • Logs: journalctl -u pulse-docker-agent -f

Rollback

# Force legacy installer
export PULSE_INSTALLER_V2=0
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- ...

Contact support or the Pulse engineering team if issues arise during rollout.