Contributing to HAM v3.0

Project Status

Current Status: Production Ready ✅

• ✅ All 22 production-grade Quadlets created
• ✅ Go installer implementation complete (5.9 MB binary)
• ✅ Interactive TUI with cleanup & Pi-hole integration
• ✅ Rootful/rootless deployment support
• ✅ Template-First approach implemented
• ✅ Tested on Podman Machine

Remaining: Pi-hole testing on real hardware

Development History

Phase 1: Quadlet Conversion (Complete)

• Converted all podman-compose files to Quadlets
• Created 22 quadlet files with production best practices
• Added health checks, auto-updates, resource limits
• See quadlets/ directory

Phase 2: Project Structures (Complete)

• Go implementation: Working, 700 LoC
• Rust implementation: Requires Rust 1.56+
• Both project structures complete

Phase 3: Installer Implementation (Complete)

• Template-First approach implemented in Go
• Interactive TUI with configuration wizard
• Pre-deployment cleanup system
• Pi-hole rootful deployment support
• Password manager integration
• System configuration automation

Testing on Podman Machine

Successfully tested services:

• ✅ Caddy (reverse proxy)
• ✅ Home Assistant (with DHCP disabled for VM)
• ✅ MQTT
• ✅ ESPHome
• ✅ Whisper, Piper, OpenWakeWord
• ✅ Node-RED (pre-configured with HA integration)

Known VM Limitations:

• Home Assistant DHCP discovery disabled (needs elevated privileges)
• Health checks simplified (curl not always available)
• Pi-hole requires real hardware (host networking needed)

Code Structure

implementations/
├── go-installer/          # Main implementation (production-ready)
│   ├── cmd/
│   │   ├── ham-installer-interactive/  # Full TUI installer
│   │   └── ham-deploy-test/            # Testing/deployment tool
│   ├── internal/
│   │   ├── approaches/    # Template-First, Dynamic, Hybrid
│   │   ├── cleanup/       # Pre-deployment cleanup
│   │   ├── config/        # Configuration handling
│   │   ├── installer/     # Deployment logic
│   │   ├── secrets/       # Password manager integration
│   │   ├── system/        # System configuration (Pi-hole)
│   │   ├── template/      # Template rendering
│   │   └── tui/          # Interactive prompts
│   └── templates/        # Go templates for quadlets
└── rust-installer/       # Rust implementation (requires 1.56+)

Key Technical Decisions

Rootful vs Rootless

• Rootless (default): Caddy, Home Assistant, all optional services
• Rootful (sudo): Pi-hole only (requires host networking & DNS)

Configuration Approach

1. TUI builds config.toml
2. Template renderer generates quadlets from config
3. Deployer handles rootful/rootless separately
4. systemd manages service lifecycle

Template System

• Uses Go's text/template with Sprig functions
• Templates embedded in binary via embed
• Supports both .container and .network quadlets
• Config files (Caddyfile, settings.js, etc.) included

Recent Fixes

Home Assistant Crash Loop (Nov 24, 2025)

Problem: Container restarting every 15 seconds Causes:

1. DHCP discovery requiring elevated privileges
2. Health check using unavailable curl command
3. Auto-restart on health check failure

Solutions:

1. Disabled DHCP in configuration.yaml
2. Simplified health check to use wget
3. Removed health check entirely for VM testing
4. Increased RestartSec to 30 seconds

Result: Stable operation, no crashes

Node-RED + Home Assistant Integration

Feature: Pre-configured integration Implementation:

• Auto-installs node-red-contrib-home-assistant-websocket
• Pre-configured settings.js with HA server URL
• Welcome flow with setup instructions
• User only needs to add access token

Building

cd implementations/go-installer

# Full interactive installer
go build -o ham-installer ./cmd/ham-installer-interactive

# Testing/deployment tool
go build -o ham-deploy-test ./cmd/ham-deploy-test

Testing

Local Testing

./ham-installer
# Follow TUI prompts

Podman Machine Testing

# Create test machine
podman machine init testing
podman machine start testing

# Deploy
./ham-installer
# Choose option 2: Deploy to Podman Machine

# Access services via port forwarding
podman machine ssh testing -L 8123:localhost:8123 -L 9080:localhost:8080

Real Hardware Testing

Pi-hole and full feature testing requires:

• Physical machine or proper VM with host networking
• Fedora Silverblue (recommended) or similar
• Sudo access for rootful services

Documentation

• README.md - Project overview & quick links
• MASTER_PLAN.md - Comprehensive plan & architecture
• QUICK_START.md - User quick start guide
• INSTALL_SILVERBLUE.md - Detailed installation guide
• TECHNICAL_REFERENCE.md - Implementation details
• QUADLET_BEST_PRACTICES.md - Quadlet reference

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Test thoroughly: Especially on Podman Machine
5. Update documentation: Keep docs in sync with code
6. Submit a pull request

Code Style

Go

• Follow standard Go conventions
• Use gofmt for formatting
• Add godoc comments for exported functions
• Use logrus for logging

Templates

• Use descriptive variable names
• Comment complex logic
• Test with various configurations
• Handle missing values gracefully

Future Work

High Priority

• Pi-hole testing on real hardware
• Complete TUI integration for all services
• Add Traefik support (alongside Caddy)
• WireGuard VPN implementation

Medium Priority

• Bitwarden/Vaultwarden integration
• Backup automation
• Service health monitoring
• Auto-rollback on failure

Low Priority

• Extended service catalog (120+ services)
• Service bundles/presets
• Cost calculator
• Migration from Docker Compose

Questions?

• Check MASTER_PLAN.md for architecture
• See TECHNICAL_REFERENCE.md for implementation details
• Review closed issues for similar problems
• Open a new issue with your question

License

See LICENSE file for details.