From Bash Script to Web Application: The CrowdSec Manager Evolution
Migration
CrowdSec Manager has evolved from a command-line bash script into a full-featured web application. This migration represents a significant leap forward in usability, functionality, and maintainability. In this post, we’ll explore the journey, the improvements, and how to migrate from the old script-based approach to the new web-based solution.
The Evolution: Why We Migrated
The Original Bash Script
The original CrowdSec Manager was a comprehensive bash script (setup_crowdsec_manager.sh) that provided 15 menu-driven options for managing CrowdSec in a Pangolin Docker environment. While functional, it had limitations:
-
Terminal-only interface: Required SSH access and command-line knowledge
-
Limited interactivity: Menu-driven navigation with text prompts
-
No persistent state: Settings weren’t saved between sessions
-
Manual log viewing: Required terminal commands to view logs
-
No real-time monitoring: Static views of system status
-
Limited automation: Difficult to integrate with other tools
The New Web Application
The new CrowdSec Manager is a modern, full-stack application built with:
-
Backend: Go (Golang) with Gin web framework
-
Frontend: React 18 with TypeScript, Vite, and Shadcn/ui components
-
Architecture: RESTful API with WebSocket support for real-time features
-
Database: SQLite for persistent settings and configuration
-
Deployment: Docker container for easy deployment
Key Improvements
1. Modern Web Interface
Before (Bash Script):
===========================================
CrowdSec Manager - Main Menu
===========================================
1. Check System Health
2. Run Complete Diagnostic Check
...
Enter your choice [0-15]:
After (Web Application):
-
Beautiful, responsive web UI accessible from any browser
-
Real-time dashboard with live status updates
-
Intuitive navigation with sidebar menu
-
Visual indicators for system health
-
Interactive charts and graphs for metrics
2. Real-Time Features
New Capabilities:
-
Live Log Streaming: WebSocket-based real-time log viewing for all services
-
Live Status Updates: Automatic refresh of container status and metrics
-
Real-Time Decision Monitoring: Watch security decisions as they happen
-
Live Alert Feed: See security alerts in real-time
Before: Static log viewing required manual terminal commands
docker logs -f crowdsec
After: Click a button in the web UI to stream logs with automatic scrolling and filtering
3. Enhanced IP Management
New Features:
-
Visual IP Security Dashboard: See all blocked IPs with reasons and timestamps
-
Bulk Operations: Manage multiple IPs at once
-
IP History: Track IP actions over time
-
Advanced Filtering: Search and filter decisions by type, reason, or date
-
Quick Actions: One-click unban, whitelist, or block operations
Before: Manual IP entry through text prompts
Enter IP to unban: 1.2.3.4
After: Visual table with search, sort, and bulk actions
4. Comprehensive Backup System
New Capabilities:
-
Automated Backups: Schedule backups with cron job integration
-
Backup Management UI: View, restore, and delete backups visually
-
Retention Policies: Automatic cleanup of old backups
-
Backup Verification: Check backup integrity before restoration
-
One-Click Restore: Restore entire system with a single click
Before: Manual backup creation required script execution
After: Automated scheduling with visual management interface
5. Advanced Log Analysis
New Features:
-
Multi-Service Log Viewer: View logs from CrowdSec, Traefik, Pangolin, and Gerbil
-
Advanced Traefik Analysis: Statistics, top IPs, status codes, and more
-
Log Filtering: Filter by service, date, or search term
-
Export Capabilities: Download logs for analysis
-
Real-Time Streaming: Watch logs as they’re generated
Before: Separate commands for each service
docker logs crowdsec --tail 50
docker logs traefik --tail 50
After: Unified log viewer with tabs for each service and real-time streaming
6. Decision and Alert Analysis
New Capabilities:
-
Decision Analysis Dashboard: Visual breakdown of security decisions
-
Alert Analysis: Detailed analysis of CrowdSec alerts
-
Trend Visualization: See security trends over time
-
Export Reports: Generate reports for analysis
Before: Simple list of blocked IPs
After: Comprehensive analysis with charts and statistics
7. Enhanced Configuration Management
New Features:
-
Visual Configuration Editor: Edit CrowdSec and Traefik configs through the UI
-
Settings Persistence: Save preferences and settings in database
-
Configuration Validation: Validate configs before applying
-
Version History: Track configuration changes
Before: Manual file editing with vi/nano
After: Web-based editor with syntax highlighting and validation
8. Service Management
New Capabilities:
-
Service Control Panel: Start, stop, restart services from the UI
-
Service Health Monitoring: Real-time status of all services
-
Graceful Shutdown: Safe shutdown procedures
-
Service Dependencies: Visual representation of service relationships
9. Cron Job Management
New Feature:
-
Visual Cron Editor: Create and manage cron jobs through the UI
-
Pre-configured Jobs: Templates for common tasks
-
Job History: View execution history and logs
10. System Updates
New Capabilities:
-
Update Management UI: Update Docker images with custom tags
-
Rollback Support: Automatic rollback on failure
-
Update History: Track update operations
-
Flexible Updates: Update with or without CrowdSec
Feature Comparison
| Feature | Bash Script | Web Application |
|---------|------------|-----------------|
| Interface | Terminal menu | Modern web UI |
| Access | SSH required | Browser from anywhere |
| Real-Time Logs | Manual docker logs -f | WebSocket streaming |
| IP Management | Text prompts | Visual table with search |
| Backup Management | Manual script execution | Automated with UI |
| Log Analysis | Basic tail commands | Advanced analysis with stats |
| Decision Analysis | Simple list | Charts and trends |
| Configuration | File editing | Web-based editor |
| Multi-User | Single terminal session | Multiple concurrent users |
| Mobile Access | Not practical | Responsive design |
| API Access | N/A | Full REST API |
| Settings Persistence | None | SQLite database |
| Automation | Limited | Cron job integration |
Migration Guide
For Existing Bash Script Users
If you’re currently using the bash script version, here’s how to migrate:
Step 1: Backup Your Current Setup
# Create a backup of your current configuration
./setup_crowdsec_manager.sh
# Select option for backup (if available)
# Or manually backup:
cp -r /root/config ./backup-config-$(date +%Y%m%d)
Step 2: Prepare for Migration
# Ensure you have Docker and Docker Compose installed
docker --version
docker compose version
# Create required directories
sudo mkdir -p /root/config /root/config/traefik/logs
mkdir -p ./backups ./data
# Ensure the pangolin network exists
docker network create pangolin
Step 3: Deploy the Web Application
# Pull the latest image
docker pull hhftechnology/crowdsec-manager:latest
# Create docker-compose.yml (see README.md for full config)
# Start the container
docker compose up -d
# Verify it's running
docker ps | grep crowdsec-manager
curl http://localhost:8080/health
Step 4: Access the Web Interface
-
Open your browser to
http://your-server-ip:8080 -
Verify all services are running via the Dashboard
-
Whitelist your current IP (Whitelist Management page)
-
Review your existing configuration
Step 5: Migrate Settings
The web application will automatically detect your existing CrowdSec and Traefik configurations. However, you may want to:
-
Review Whitelists: Check that all whitelisted IPs are present
-
Verify Scenarios: Ensure custom scenarios are still active
-
Check Captcha Setup: Verify captcha configuration if previously set up
-
Review Backups: Create a new backup through the UI
Step 6: Set Up Automation
-
Configure Automated Backups: Set up cron jobs through the Cron Management page
-
Schedule Health Checks: Use the API to set up monitoring
-
Configure Alerts: Set up notifications for critical events
API Access
One of the major advantages of the new application is full API access. You can now integrate CrowdSec Manager with other tools:
Example: Automated IP Whitelisting
#!/bin/bash
# Whitelist current IP automatically
curl -X POST http://localhost:8080/api/whitelist/current \
-H "Content-Type: application/json" \
-d '{"add_to_crowdsec": true, "add_to_traefik": true}'
Example: Health Check Monitoring
#!/bin/bash
# Check system health and alert if issues found
HEALTH=$(curl -s http://localhost:8080/api/health/complete)
if echo "$HEALTH" | grep -q '"status":"error"'; then
# Send alert notification
echo "CrowdSec Manager health check failed!"
fi
Example: Automated Backup
#!/bin/bash
# Create backup via API
curl -X POST http://localhost:8080/api/backup/create \
-H "Content-Type: application/json" \
-d '{"dry_run": false}'
Technical Architecture
Backend (Go)
-
Framework: Gin web framework for high performance
-
Docker Integration: Direct Docker API access for container management
-
Database: SQLite for lightweight, file-based storage
-
Logging: Structured logging with configurable levels
-
API: RESTful API with comprehensive error handling
Frontend (React)
-
Framework: React 18 with TypeScript
-
Build Tool: Vite for fast development and builds
-
UI Components: Shadcn/ui for modern, accessible components
-
State Management: TanStack Query for server state
-
Routing: React Router for navigation
-
Styling: Tailwind CSS for responsive design
Key Technologies
-
WebSockets: Real-time log streaming and updates
-
Docker API: Direct container management
-
File System Access: Read/write configuration files
-
Cron Integration: Schedule automated tasks
-
Backup System: Comprehensive backup and restore
Benefits of the Migration
For End Users
-
Easier Access: No SSH required, access from any browser
-
Better UX: Intuitive interface with visual feedback
-
Real-Time Monitoring: See what’s happening as it happens
-
Mobile Friendly: Responsive design works on phones/tablets
-
Multi-User Support: Multiple people can use it simultaneously
For Administrators
-
Better Monitoring: Comprehensive dashboards and analytics
-
Automation: Cron job integration for scheduled tasks
-
API Access: Integrate with other tools and scripts
-
Audit Trail: Database tracks all operations
-
Easier Maintenance: Web-based configuration management
For Developers
-
Extensible: Well-structured codebase for adding features
-
API-First: Full REST API for integration
-
Modern Stack: Go and React are industry-standard technologies
-
Type Safety: TypeScript prevents common errors
-
Maintainable: Clean architecture and separation of concerns
What’s Next?
The migration to a web application opens up many possibilities:
-
Mobile App: Native mobile applications using the API
-
Multi-Instance Support: Manage multiple CrowdSec installations
-
Advanced Analytics: Machine learning for threat detection
-
Integration Hub: Connect with other security tools
-
Notification System: Email, Slack, Discord integrations
-
Role-Based Access: Multi-user with permissions
-
Audit Logging: Comprehensive audit trail
-
Plugin System: Extensible architecture for custom features
Conclusion
The migration from bash script to web application represents a significant evolution in CrowdSec Manager. While the bash script served its purpose well, the new web application provides:
-
Better User Experience: Modern, intuitive interface
-
More Features: Real-time monitoring, advanced analysis, automation
-
Better Integration: API access for automation and tooling
-
Easier Maintenance: Web-based configuration and management
-
Future-Proof: Modern architecture ready for new features
Whether you’re a long-time user of the bash script or new to CrowdSec Manager, the web application provides a superior experience for managing your CrowdSec security stack.
Getting Started
Ready to make the switch? Check out the README.md for installation instructions and the USAGE.md for detailed usage guide.
Important: This is currently BETA software. Always test on a non-production environment first!
Support
-
Issues: GitHub Issues
-
Discussions: GitHub Discussions
Built with 
for the CrowdSec community
Network pangolin Created