captnio/captn repository overview

⁠captn

Intelligent Container Updater

captn is an intelligent, rule-based container updater that automatically manages container updates using semantic versioning and registry metadata.
Keep your containers up-to-date with confidence and control.

⁠✨ Features

• 🎯 Rule-Driven Updates - Define custom update policies for different containers
• 🌐 Multi-Registry Support - Docker Hub, GitHub Container Registry
• 📈 Progressive Upgrades - Apply multiple updates in sequence
• 👀 Dry-Run Mode - Preview changes before applying them
• 📰 Notifications - Get notified about update status and results via Telegram and E-Mail
• 🧹 Automatic Cleanup - Remove unused images and old backup containers
• 📊 Comprehensive Logging - Detailed logging with configurable levels
• ⏮️ Rollback Support - Automatic rollback on container startup and custom post-script failures
• ⏰ Scheduled Execution - Built-in scheduler with cron expression support

⁠🚧 Development Status

We welcome testers and contributors! If you'd like to help shape captn, we're especially looking for contributions in:

• 📝 Documentation - Help improve guides, examples, and explanations
• 🧪 Testing - Test captn in different environments and report issues
• 🏗️ Repository Optimization - Create wiki pages, issue templates, and improve project structure

Your feedback and contributions are highly valued as we work towards a stable release!

⁠🚀 Quick Start

⁠1. Create Directories

# Create directories for configuration and log files
mkdir -p ~/captn/{conf,logs}

⁠2. Run captn Container

# Run captn container with proper volume mounts
docker run -d \
  --name captn \
  --restart unless-stopped \
  -e TZ=Europe/Berlin \
  -v /etc/localtime:/etc/localtime:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/captn/conf:/app/conf \
  -v ~/captn/logs:/app/logs \
  captnio/captn:0.9.0

⁠3. First Run (Dry-Run Mode)

By default, captn runs in normal mode but all containers are assigned to the default rule which does not allow any updates at all for safety reasons. To get a preview of what captn would do, you can:

1. Assign containers to different rules in the configuration file

2. Run in dry-run mode to see what would be updated:

   # Preview what would be updated
   docker exec captn captn --dry-run
   
   # Run actual updates (after reviewing dry-run results)
   docker exec captn captn
   

   Copy

⁠🔧 Advanced Features

⁠Pre/Post Scripts

captn supports executing custom scripts before and after updates:

• Pre-scripts: Run before container updates (backups, health checks)
• Post-scripts: Run after successful updates (verification, notifications, customizations, post-update or cleanup tasks)
• Container-specific: Scripts can be tailored to specific containers
• Failure handling: Configure whether to continue or skip/rollback on script failures

⁠Notifications

Get updates about captn's activities:

• Update status and results
• Error notifications
• Summary reports

⁠Currently supported notification methods

• Telegram: Quick update summaries via Telegram Bot API
• E-Mail: SMTP-based email notifications with detailed HTML reports

⁠📚 Documentation

For detailed configuration options, advanced usage, and troubleshooting, please refer to:

• Introduction & Getting Started⁠ - Overview and concepts
• CLI Reference⁠ - Command-line usage
• Configuration Reference⁠ - All configuration options
• Scripts Guide⁠ - Pre/post-update scripts

⁠🤝 Contributing

We welcome contributions! captn is in active development and we're particularly interested in:

• Documentation improvements - Enhance existing docs, add examples, create tutorials
• Testing and bug reports - Help us identify and fix issues
• Repository infrastructure - Help create wiki pages, issue templates, PR templates, and improve project organization
• Code contributions - New features, optimizations, and bug fixes

Feel free to open an issue to discuss your ideas or submit a pull request directly. Every contribution, no matter how small, is appreciated!

⁠📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE⁠ file for details.

⁠💬 Support

• Issues: GitHub Issues⁠
• Discussions: GitHub Discussions⁠
• Documentation: Docs⁠

⚠️ Important: Always test with --dry-run first to understand what captn will do before running actual updates.