Deploying BunkerWeb
BunkerWeb is a next-generation, open-source Web Application Firewall (WAF) built on NGINX that provides comprehensive security for web services with minimal configuration. Designed to make security by default great again, BunkerWeb acts as a reverse proxy and security shield in front of your web applications, blocking attacks before they can hit while guaranteeing confidentiality, integrity, and availability of your data. With integrated ModSecurity WAF with OWASP Core Rule Set, automatic Let’s Encrypt SSL/TLS certificates, state-of-the-art HTTP security headers, intelligent bot detection and mitigation, DDoS protection, custom Lua rules, multisite virtual hosting support, comprehensive web UI for management, and seamless integration into existing environments, BunkerWeb enables you to protect your web applications, APIs, and services against OWASP Top 10 threats, malicious bots, DDoS attacks, and sophisticated cyber threats.
Why BunkerWeb?
BunkerWeb stands out as a powerful security solution for web applications:
- NGINX-based Reverse Proxy: Full-featured web server with reverse proxy capabilities
- ModSecurity WAF Integration: Industry-standard Web Application Firewall
- OWASP Core Rule Set: Comprehensive rules against OWASP Top 10 threats
- Automatic SSL/TLS: Let’s Encrypt integration with transparent certificate management
- HTTP Security Headers: HSTS, CSP, X-Frame-Options, and other security headers
- Bot Protection: Multiple challenge types (cookie, JavaScript, captcha, hCaptcha, reCAPTCHA)
- DDoS Mitigation: Rate limiting, connection limits, and intelligent filtering
- Request Limiting: Connection and request rate controls per client
- Behavior-based Ban System: Automatic banning based on HTTP status codes
- Multisite Support: Virtual hosting for multiple web applications
- Custom Rules: Lua scripting for custom security rules
- Reverse Proxy Features: Load balancing, caching, compression (gzip, brotli)
- Web UI: User-friendly interface for configuration and monitoring
- Advanced Logging: Detailed attack logs and security event tracking
- Plugin System: Extend with official plugins (Discord, Slack, ClamAV, etc.)
- Multiple Databases: SQLite, MariaDB, MySQL, PostgreSQL support
- Professional Services: Technical support and custom development available
- Free and Open Source: AGPLv3 licensed with active community
- Cross-platform: Linux, Docker, Docker Swarm, Kubernetes, Azure support
BunkerWeb is ideal for protecting web applications from attacks, securing API gateways, defending microservices architectures, managing multiple virtual hosts, protecting against DDoS attacks, enabling OWASP compliance, and securing development and production environments. With persistent storage on Klutch.sh, your WAF configuration is always protected and synchronized.
Prerequisites
Before deploying BunkerWeb, ensure you have:
- A Klutch.sh account
- A GitHub repository with your BunkerWeb deployment configuration
- Basic familiarity with Docker and Git
- Knowledge of your upstream web services (domains/IPs)
- HTTPS support required (automatic with Let’s Encrypt)
- Custom domains for protected services (recommended)
- Understanding of web application security concepts
- SMTP credentials for security notifications (optional)
- Time for initial WAF tuning and false positive management
Important Considerations
Deploying BunkerWeb
Create a New Project
Log in to your Klutch.sh dashboard and create a new project for your BunkerWeb Web Application Firewall.
Prepare Your Repository
Create a GitHub repository with the following structure for your BunkerWeb deployment:
bunkerweb-deploy/├─ Dockerfile├─ docker-compose.yml (optional, for local testing)├─ .env.example├─ entrypoint.sh├─ .gitignore└─ README.mdHere’s a Dockerfile for BunkerWeb:
FROM bunkerity/bunkerweb:latestWORKDIR /etc/bunkerweb# Update system packagesRUN apt-get update && apt-get upgrade -y && \apt-get install -y \curl \wget \&& rm -rf /var/lib/apt/lists/*# Create necessary directoriesRUN mkdir -p /data \/var/cache/bunkerweb \/var/log/bunkerweb \&& chown -R www-data:www-data /data \/var/cache/bunkerweb \/var/log/bunkerweb# Expose portEXPOSE 80 443# Health checkHEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \CMD curl -f http://localhost/ -H "Host: localhost" -k || exit 1# Run BunkerWebCMD ["bunkerweb"]Create an
.env.examplefile:Terminal window # BunkerWeb ConfigurationSERVER_NAME=yourdomain.com www.yourdomain.comAUTO_LETS_ENCRYPT=yesUSE_MODSECURITY=yesUSE_ANTIBOT=yes# Security SettingsALLOWED_METHODS=GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONSMAX_BODY_SIZE=10mRATE_LIMIT=100r/s# ModSecurity ConfigurationMODSECURITY_SEC_AUDIT_ENGINE=OnMODSECURITY_RULES=# Antibot SettingsANTIBOT_CHALLENGE=cookie# Reverse Proxy ConfigurationREVERSE_PROXY_URL=/REVERSE_PROXY_HOST=http://upstream-service:8080# Web UI (optional)API_LISTEN_PORT=5000API_WHITELIST_IP=127.0.0.1Create an
entrypoint.shfile:#!/bin/bashset -eecho "Starting BunkerWeb..."# Create necessary directoriesmkdir -p /data \/var/cache/bunkerweb \/var/log/bunkerweb# Set proper permissionschown -R www-data:www-data /data \/var/cache/bunkerweb \/var/log/bunkerweb# Export environment variablesexport SERVER_NAME=${SERVER_NAME:-yourdomain.com}export AUTO_LETS_ENCRYPT=${AUTO_LETS_ENCRYPT:-yes}export USE_MODSECURITY=${USE_MODSECURITY:-yes}export USE_ANTIBOT=${USE_ANTIBOT:-yes}export REVERSE_PROXY_HOST=${REVERSE_PROXY_HOST:-http://localhost:8080}echo "BunkerWeb configuration:"echo "- Server Name: $SERVER_NAME"echo "- Let's Encrypt: $AUTO_LETS_ENCRYPT"echo "- ModSecurity: $USE_MODSECURITY"echo "- Antibot: $USE_ANTIBOT"echo "- Upstream: $REVERSE_PROXY_HOST"# Start BunkerWebexec "$@"Create a
.gitignorefile:.envdata/logs/*.log.DS_Store.idea/*.swp*.swo/data//logs//cache/.venv/venv/env/Commit and push to your GitHub repository:
Terminal window git initgit add .git commit -m "Initial BunkerWeb WAF deployment"git remote add origin https://github.com/yourusername/bunkerweb-deploy.gitgit push -u origin mainCreate a New App
In the Klutch.sh dashboard:
- Click “Create New App”
- Select your GitHub repository containing the Dockerfile
- Choose the branch (typically
mainormaster) - Klutch.sh will automatically detect the Dockerfile in the root directory
Configure Environment Variables
Set up BunkerWeb configuration in your Klutch.sh dashboard:
Variable Description Example SERVER_NAMEProtected domain names yourdomain.com www.yourdomain.comAUTO_LETS_ENCRYPTEnable Let’s Encrypt yesUSE_MODSECURITYEnable ModSecurity WAF yesUSE_ANTIBOTEnable bot protection yesANTIBOT_CHALLENGEBot challenge type cookieorjavascriptorcaptchaREVERSE_PROXY_URLProxy URL path /REVERSE_PROXY_HOSTUpstream service address http://upstream-service:8080ALLOWED_METHODSAllowed HTTP methods GET|POST|PUT|DELETEMAX_BODY_SIZEMax request body size 10mRATE_LIMITRate limit per second 100r/sUSE_MODSECURITYEnable WAF rules yesMODSECURITY_SEC_AUDIT_ENGINEAudit engine OnConfigure Persistent Storage
BunkerWeb benefits from persistent storage for configuration and logs. Add persistent volumes:
Mount Path Description Recommended Size /dataBunkerWeb configuration and state 5GB /var/log/bunkerwebSecurity and access logs 10GB In the Klutch.sh dashboard:
- Navigate to your app settings
- Go to the “Volumes” section
- Click “Add Volume” for each mount path
- Set mount paths and sizes as specified above
- Ensure log volume has sufficient space for audit trails
Set Network Configuration
Configure your app’s network settings:
- Select traffic type: HTTP
- Recommended internal port: 80 (BunkerWeb default for HTTP, 443 for HTTPS)
- Klutch.sh will handle HTTPS termination via reverse proxy
- BunkerWeb can also handle SSL internally
Configure Custom Domains
Add custom domains for your protected services:
- Navigate to your app’s “Domains” section in Klutch.sh
- Add custom domain (e.g.,
yourdomain.com,api.yourdomain.com) - Configure DNS with CNAME record pointing to your Klutch.sh app
- Update
SERVER_NAMEenvironment variable with all domains - Wait for DNS propagation (typically 5-15 minutes)
- Verify SSL certificates are provisioned
Deploy Your App
- Review all settings and environment variables carefully
- Verify upstream services are configured
- Verify custom domains are configured
- Ensure persistent volumes are properly configured
- Click “Deploy”
- Klutch.sh will build the Docker image and start your BunkerWeb instance
- Wait for deployment to complete (typically 15-25 minutes)
- Access your BunkerWeb-protected service at your domain
- Verify security headers are in place
- Monitor logs for false positives during initial period
Initial Setup and Configuration
After deployment completes, configure your WAF.
Accessing BunkerWeb
Your protected service is accessible at: https://yourdomain.com
BunkerWeb acts as a reverse proxy, forwarding traffic to your upstream service while protecting it.
Configuring Upstream Services
Set up reverse proxy to your backend services:
- Determine your backend service address and port
- Set
REVERSE_PROXY_HOSTto backend address - Set
REVERSE_PROXY_URLto the path (typically/) - For multiple backends, configure load balancing
- Test upstream connectivity
- Verify health checks passing
Enabling ModSecurity WAF
Activate Web Application Firewall:
- Set
USE_MODSECURITY=yes - WAF uses OWASP Core Rule Set by default
- Rules analyze request/response for attacks
- Suspicious requests are blocked
- Review logs for false positives
- Adjust rules as needed
Configuring Bot Protection
Set up antibot challenge:
-
Set
USE_ANTIBOT=yes -
Choose challenge type:
cookie: Simple cookie-based challengejavascript: JavaScript execution requiredcaptcha: Google reCAPTCHA v2 challengehcaptcha: hCaptcha challengepow: Proof of Work challenge
-
Configure reCAPTCHA keys if needed
-
Legitimate bots (Google, Bing) are allowed
-
Unknown bots face challenge
-
Monitor bypass attempts
Managing HTTP Security Headers
BunkerWeb sets security headers automatically:
Strict-Transport-Security: Force HTTPSX-Frame-Options: Prevent clickjackingX-Content-Type-Options: Prevent MIME sniffingContent-Security-Policy: Control resource loadingReferrer-Policy: Control referrer informationPermissions-Policy: Control browser features
Configure via environment variables:
STRICT_TRANSPORT_SECURITY=max-age=31536000; includeSubDomainsX_FRAME_OPTIONS=DENYX_CONTENT_TYPE_OPTIONS=nosniffCONTENT_SECURITY_POLICY="default-src 'self'"Setting Rate Limiting
Configure traffic rate limits:
- Set
RATE_LIMITto requests per second - Set
RATE_LIMIT_URLfor specific paths - Set client connection limits
- Monitor for legitimate user impact
- Adjust thresholds based on traffic analysis
Managing SSL/TLS Certificates
Automatic certificate management:
- With
AUTO_LETS_ENCRYPT=yes, certificates auto-provision - Supports multiple domains
- Wildcard certificates available
- Renewal happens automatically
- No manual intervention needed
For custom certificates:
- Upload certificate files to persistent storage
- Configure certificate paths
- Support for PEM format
- Chain certificates included
Configuring Multisite Mode
Protect multiple web applications:
-
List all domains in
SERVER_NAME -
For each domain, configure upstream service:
domain1.com_REVERSE_PROXY_HOST=http://service1:8080domain2.com_REVERSE_PROXY_HOST=http://service2:8080
-
Each domain has separate security configuration
-
Settings can be domain-specific
-
Log aggregation across all sites
Creating Custom Rules
Add custom Lua rules:
- Create custom rule files
- Store in persistent storage
- BunkerWeb loads custom rules
- Syntax: Lua scripting language
- Examples for specific attack patterns
- Testing in audit mode first
Monitoring and Logging
Access security logs:
- Logs stored in
/var/log/bunkerweb - Review access logs for patterns
- Check security audit logs
- Analyze blocked requests
- Generate reports for compliance
- Export logs for external analysis
Using the Web UI (Optional)
Manage BunkerWeb configuration via web interface:
- Access at
https://yourdomain.com:5000(if configured) - View dashboard with security statistics
- See real-time attack blocking
- Manage services and configuration
- Update settings without restart
- View cached files and resources
Configuring Notifications
Send security alerts:
- Configure plugins for notifications
- Discord plugin for Discord webhooks
- Slack plugin for Slack channels
- Email notifications for critical events
- Configure alert thresholds
- Test notification delivery
Environment Variable Examples
Basic Configuration
SERVER_NAME=yourdomain.comAUTO_LETS_ENCRYPT=yesUSE_MODSECURITY=yesUSE_ANTIBOT=yesREVERSE_PROXY_HOST=http://upstream-service:8080Complete Production Configuration
# Domain ConfigurationSERVER_NAME=yourdomain.com www.yourdomain.com api.yourdomain.comMULTISITE=yes
# SSL/TLS ConfigurationAUTO_LETS_ENCRYPT=yesUSE_HTTPS=yes
# Reverse Proxy ConfigurationREVERSE_PROXY_URL=/REVERSE_PROXY_HOST=http://upstream-service:8080REVERSE_PROXY_PRESERVE_HOST=yes
# Security FeaturesUSE_MODSECURITY=yesUSE_ANTIBOT=yesANTIBOT_CHALLENGE=captchaANTIBOT_RECAPTCHA_SITEKEY=your_sitekey_hereANTIBOT_RECAPTCHA_SECRET=your_secret_here
# Rate LimitingRATE_LIMIT=100r/sLIMIT_REQ_URL=/apiLIMIT_REQ=/api 10r/s
# HTTP MethodsALLOWED_METHODS=GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONSMAX_BODY_SIZE=10m
# HTTP Security HeadersSTRICT_TRANSPORT_SECURITY=max-age=31536000; includeSubDomainsX_FRAME_OPTIONS=DENYX_CONTENT_TYPE_OPTIONS=nosniff
# PerformanceUSE_GZIP=yesUSE_BROTLI=yesGZIP_LEVEL=6
# CachingCLIENT_BODY_CACHE=yesPROXY_CACHE_VALID_200=1hPROXY_CACHE_VALID_404=10mSample Code and Getting Started
Bash - Health Check and Monitoring Script
#!/bin/bash
# BunkerWeb Health Check and Monitoring Script
BUNKERWEB_URL="${BUNKERWEB_URL:-https://yourdomain.com}"LOG_FILE="/var/log/bunkerweb/check.log"ALERT_EMAIL="${ALERT_EMAIL:-admin@yourdomain.com}"
echo "Checking BunkerWeb health..."
# Check if BunkerWeb is respondingHTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -H "User-Agent: HealthCheck" "$BUNKERWEB_URL" 2>/dev/null)
if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "301" ] || [ "$HTTP_CODE" = "302" ]; then echo "✓ BunkerWeb is healthy (HTTP $HTTP_CODE)" | tee -a "$LOG_FILE"else echo "✗ BunkerWeb health check failed (HTTP $HTTP_CODE)" | tee -a "$LOG_FILE"fi
# Check SSL certificate validityecho ""echo "Checking SSL certificate..."
CERT_EXPIRY=$(echo | openssl s_client -servername yourdomain.com \ -connect yourdomain.com:443 2>/dev/null | \ openssl x509 -noout -enddate 2>/dev/null | cut -d= -f2)
echo "Certificate expires: $CERT_EXPIRY"
# Check for blocked requests in logsecho ""echo "Analyzing security logs..."
BLOCKED_COUNT=$(grep -c "ModSecurity" /var/log/bunkerweb/access.log 2>/dev/null || echo "0")echo "✓ Blocked requests in last period: $BLOCKED_COUNT"
# Check disk spaceecho ""echo "Checking disk space..."
DISK_USAGE=$(du -sh /var/log/bunkerweb | awk '{print $1}')echo "✓ Log volume usage: $DISK_USAGE"
# Generate reportecho ""echo "Health check completed at $(date)" | tee -a "$LOG_FILE"Lua - Custom Security Rule
-- BunkerWeb Custom Security Rule-- File: /data/custom/custom_rule.lua
local bunkerweb = require "bunkerweb"local logger = bunkerweb:get_variable("LOG")
-- Check for suspicious patternslocal uri = bunkerweb:get_variable("URI")local method = bunkerweb:get_variable("METHOD")local user_agent = bunkerweb:get_variable("HTTP_USER_AGENT")
-- Block requests with suspicious patternsif string.find(uri, "admin") and method == "POST" then if not string.find(user_agent, "Mozilla") then logger:log(ngx.ALERT, "Suspicious admin access from non-browser user agent") bunkerweb:set_variable("USE_MODSECURITY", "on") return 403 endend
-- Rate limit specific endpointsif string.find(uri, "/api/login") then local ip = bunkerweb:get_variable("REMOTE_ADDR") -- Implement rate limiting logic logger:log(ngx.INFO, "Login attempt from IP: " .. ip)end
-- Check for missing security headers in responseslocal response_headers = bunkerweb:get_variable("RESP_HEADERS")if not string.find(response_headers, "Strict-Transport-Security") then logger:log(ngx.WARN, "Missing HSTS header in response") bunkerweb:set_variable("RESP_HEADERS", response_headers .. "Strict-Transport-Security: max-age=31536000")end
return ngx.OKcURL - Testing BunkerWeb Protection
# BunkerWeb Protection Testing Examples
# Test basic connectivitycurl -v https://yourdomain.com
# Test bot challenge responsecurl -v "https://yourdomain.com/" \ -H "User-Agent: Unknown-Bot"
# Test rate limitingfor i in {1..150}; do curl -s "https://yourdomain.com/api" > /dev/nulldone
# Test suspicious payload (should be blocked by ModSecurity)curl -v "https://yourdomain.com/?id=1' OR '1'='1"
# Test with custom headerscurl -v https://yourdomain.com \ -H "X-Custom-Header: value" \ -H "Referer: https://example.com"
# Test POST requestcurl -X POST https://yourdomain.com/api \ -H "Content-Type: application/json" \ -d '{"test": "data"}'
# Check security headerscurl -I https://yourdomain.com | grep -E "Security|HSTS"
# Test with different User-Agent stringscurl -A "Mozilla/5.0" https://yourdomain.comcurl -A "curl" https://yourdomain.com
# Monitor blocked requests in real-timetail -f /var/log/bunkerweb/access.log | grep -E "blocked|denied|403"Web Application Firewall Best Practices
Rule Management
Maintain effective security rules:
- Start in Audit Mode: Run ModSecurity without blocking initially
- Review False Positives: Identify legitimate requests being blocked
- Tune Rules: Disable overly aggressive rules
- Custom Rules: Add rules for application-specific threats
- Regular Updates: Keep OWASP Core Rule Set updated
- Test Changes: Verify rules don’t break functionality
Performance Optimization
Balance security and performance:
- Caching: Enable caching for static content
- Compression: Use gzip/brotli for text responses
- Connection Limits: Prevent resource exhaustion
- Upstream Health Checks: Route around failed backends
- Session Persistence: Maintain session affinity if needed
- Monitor Response Times: Track impact of WAF rules
SSL/TLS Management
Ensure secure communications:
- Certificate Monitoring: Track expiration dates
- HSTS Headers: Enable strict transport security
- Certificate Pinning: Optional for high-security apps
- TLS Version Control: Enforce minimum TLS 1.2/1.3
- Cipher Suites: Use strong cipher configurations
- Regular Testing: Verify SSL/TLS configuration
Attack Monitoring and Response
Analyze security events:
- Alert Thresholds: Set for critical threats
- Log Aggregation: Collect logs from all instances
- Incident Response: Plan response procedures
- Blocklist Management: Maintain IP/domain block lists
- Threat Intelligence: Subscribe to threat feeds
- Regular Audits: Review security posture
Troubleshooting
Common Issues and Solutions
Issue: Legitimate requests being blocked by ModSecurity
Solutions:
- Review ModSecurity audit logs
- Identify specific rule causing blocks
- Test rule in audit mode first
- Create rule exception for legitimate pattern
- Contact BunkerWeb support for rule tuning
Issue: SSL certificate not renewing
Troubleshooting:
- Verify domain is publicly accessible
- Check DNS records pointing correctly
- Review Let’s Encrypt logs for errors
- Ensure port 443 is accessible externally
- Test renewal with
--dry-runfirst
Issue: Upstream service not responding
Solutions:
- Verify upstream service is running
- Check network connectivity
- Test upstream health endpoint
- Review upstream service logs
- Configure health checks
- Verify reverse proxy configuration
Issue: Rate limiting blocking legitimate traffic
Troubleshooting:
- Check current rate limit settings
- Analyze traffic patterns
- Increase
RATE_LIMITif needed - Create exceptions for known IPs
- Monitor false positives
- Adjust per-endpoint limits
Issue: Web UI not accessible
Solutions:
- Verify port 5000 configured correctly
- Check API firewall rules
- Verify credentials correct
- Review API logs for errors
- Test connectivity to management port
- Check persistent volume mounted
Updating BunkerWeb
To update BunkerWeb to a newer version:
- Update Dockerfile with latest version tag
- Commit and push to GitHub
- Klutch.sh automatically rebuilds
- Review release notes for breaking changes
- Test security rules still effective
- Monitor logs after update
- Verify all domains protected correctly
Use Cases
Web Application Protection
- Protect traditional web applications
- Block SQL injection attacks
- Prevent XSS vulnerabilities
- Defend against CSRF attacks
API Security
- Protect REST/GraphQL APIs
- Rate limiting for API endpoints
- Request validation
- Response security headers
Microservices Defense
- Protect microservices architecture
- Service-to-service security
- Container orchestration integration
- Distributed threat detection
Multi-tenant Applications
- Isolate tenant traffic
- Per-tenant security policies
- Custom rules per tenant
- Audit trail separation
DDoS Mitigation
- Rate limiting protection
- Connection state management
- Bad behavior detection
- Geographic filtering
Additional Resources
- BunkerWeb Official Website - Project information and solutions
- BunkerWeb Documentation - Complete guides and references
- BunkerWeb GitHub Repository - Source code and issues
- BunkerWeb Discord Community - Community support and discussions
- BunkerWeb Live Demo - Test the WAF interactively
- BunkerWeb UI Demo - Test the management interface
- OWASP Top 10 - Common web vulnerabilities
- Klutch.sh Getting Started Guide
- Klutch.sh Volumes Documentation
- Klutch.sh Custom Domains Guide
Conclusion
Deploying BunkerWeb on Klutch.sh provides you with a powerful, flexible, and comprehensive Web Application Firewall that protects your web services against modern cyber threats. With integrated ModSecurity WAF with OWASP Core Rule Set, automatic SSL/TLS certificate management, bot protection with multiple challenge types, DDoS mitigation, custom Lua rules, multisite virtual hosting, detailed security logging, and professional web UI management, BunkerWeb enables you to implement “security by default” for your web applications, APIs, and services. Klutch.sh’s managed infrastructure ensures your security gateway is always available, performant, and synchronized across deployments, allowing you to focus on building applications while BunkerWeb protects them.
Start protecting your web applications today by deploying BunkerWeb on Klutch.sh and experience enterprise-grade security with open-source transparency and control.