Bash Production Toolkit

Production-ready Bash libraries for logging, file operations, error handling, alerting, and system detection.

Features

• Structured Logging - journald integration, JSON output, log rotation
• Atomic File Operations - Race-condition prevention, secure temp files
• Domain Error Handlers - Docker, network, systemd error recovery
• Alert System - Generic webhook alerts (Mattermost/Slack/Discord) with rate limiting
• Device Detection - Multi-device support with architecture detection
• Path Utilities - Relative path calculation, markdown-aware operations
• Retry & Backoff - Exponential backoff with jitter, bounded retries

Quick Start

#!/bin/bash
set -uo pipefail

# Source the libraries
source /path/to/bash-production-toolkit/src/foundation/logging.sh
source /path/to/bash-production-toolkit/src/foundation/secure-file-utils.sh

# Use them
log_info "Application started"
sfu_write_file "config data" "/var/lib/myapp/config.txt"
log_notice "Configuration saved"

Installation

git clone https://github.com/fidpa/bash-production-toolkit.git

Then source the libraries you need in your scripts:

TOOLKIT="/path/to/bash-production-toolkit/src"
source "${TOOLKIT}/foundation/logging.sh"

Libraries

Foundation

Library	Purpose
logging.sh	Structured logging with journald, JSON, file rotation
simple-logging.sh	Lightweight logging for hooks and cross-platform scripts
secure-file-utils.sh	Atomic file operations, path validation
error-handling.sh	Domain-specific error handlers with recovery

Monitoring

Library	Purpose
alerts.sh	Generic webhook alerts with rate limiting (Mattermost/Slack/Discord)
smart-alerts.sh	Event tracking with grace periods

Utilities

Library	Purpose
backup-safety.sh	Backup target validation, mountpoint checks
device-detection.sh	Multi-device identification and routing
path-calculator.sh	Path manipulation for documentation tools
retry.sh	Exponential backoff and bounded retry for unreliable operations

Requirements

• Bash 4.0+
• Standard Unix utilities (coreutils)
• Optional: jq (for JSON features), curl (for webhook alerts)

Documentation

Full documentation is available in the docs/ directory:

• Overview
• Setup Guide - Installation, configuration, systemd integration
• Architecture - Library dependencies and patterns
• Troubleshooting - Common issues and solutions

Library Documentation

• Foundation Libraries - Logging, file operations, error handling
• Monitoring Libraries - Webhook alerts, smart alerts
• Utility Libraries - Device detection, path utilities

Examples

See the examples/ directory for ready-to-run scripts:

./examples/01-logging-basics.sh
./examples/02-file-operations.sh
./examples/03-webhook-alerts.sh
./examples/07-self-healing-daemon.sh   # resilient supervise loop (retry + lock + alerts)

Testing

The repository ships a dependency-free test suite (pure Bash, no bats):

bash tests/run-all.sh

It runs unit tests for retry.sh and a smoke test that executes the dependency-free examples. CI (ci.yml) runs ShellCheck, a Bash syntax check, and this suite on every push and pull request.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Request a feature
• 🔧 Pull Requests: Fork, make changes, submit PR

Support

• 📖 Documentation: docs/
• 🐛 Bug Reports: GitHub Issues
• 🔒 Security: See SECURITY.md

License

MIT License - see LICENSE for details.

Author

Marc Allgeier (@fidpa)