Charon/.github/skills/integration-test-crowdsec-startup.SKILL.md

name, version, description, author, license, tags, compatibility, requirements, environment_variables, parameters, outputs, metadata

name	version	description	author	license	tags	compatibility	requirements	environment_variables	parameters	outputs	metadata
integration-test-crowdsec-startup	1.0.0	Test CrowdSec startup sequence, initialization, and error handling	Charon Project	MIT	integration crowdsec startup initialization resilience	os shells linux darwin bash	name version optional docker >=24.0 false name version optional curl >=7.0 false	name description default required STARTUP_TIMEOUT Maximum wait time for startup in seconds 60 false	name type description default required verbose boolean Enable verbose output false false	name type description test_results stdout Startup test results	category subcategory execution_time risk_level ci_cd_safe requires_network idempotent integration-test startup medium low true true true

Integration Test CrowdSec Startup

Overview

Tests the CrowdSec startup sequence and initialization process. This skill validates that CrowdSec components (LAPI, bouncer) start correctly, handle initialization errors gracefully, and recover from common startup failures. It ensures the system is resilient to network issues, configuration problems, and timing-related edge cases.

Proper startup behavior is critical for production deployments and automated container orchestration.

Prerequisites

• Docker 24.0 or higher installed and running
• curl 7.0 or higher for health checks
• Docker Compose for orchestration
• Network connectivity for pulling images

Usage

Basic Usage

Run CrowdSec startup tests:

cd /path/to/charon
.github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

Verbose Mode

Run with detailed startup logging:

VERBOSE=1 .github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

Custom Timeout

Run with extended startup timeout:

STARTUP_TIMEOUT=120 .github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

CI/CD Integration

For use in GitHub Actions workflows:

- name: Test CrowdSec Startup
  run: .github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup
  timeout-minutes: 5

Parameters

Parameter	Type	Required	Default	Description
verbose	boolean	No	false	Enable verbose output

Environment Variables

Variable	Required	Default	Description
STARTUP_TIMEOUT	No	60	Maximum wait for startup (seconds)
SKIP_CLEANUP	No	false	Skip container cleanup after tests
CROWDSEC_VERSION	No	latest	CrowdSec image version to test

Outputs

Success Exit Code

• 0: All startup tests passed

Error Exit Codes

• 1: One or more tests failed
• 2: Startup timeout exceeded
• 3: Configuration errors detected
• 4: Health check failed

Console Output

Example output:

=== Testing CrowdSec Startup Sequence ===
✓ LAPI Initialization: Ready in 8s
✓ Database Migration: Successful
✓ Bouncer Registration: Successful
✓ Configuration Validation: No errors
✓ Health Check: All services healthy
✓ Graceful Shutdown: Clean exit
✓ Restart Resilience: Fast recovery

All CrowdSec startup tests passed!

Test Coverage

This skill validates:

1. Clean Startup:

   • LAPI starts and becomes ready
   • Database schema migration
   • Configuration loading
   • API endpoint availability

2. Bouncer Initialization:

   • Bouncer registers with LAPI
   • API key generation/validation
   • Decision cache initialization
   • First sync successful

3. Error Handling:

   • Invalid configuration detection
   • Missing database handling
   • Network timeout recovery
   • Retry mechanisms

4. Edge Cases:

   • LAPI not ready on first attempt
   • Race conditions in initialization
   • Concurrent bouncer registrations
   • Configuration hot-reload

5. Resilience:

   • Graceful shutdown
   • Fast restart (warm start)
   • State persistence
   • No resource leaks

Examples

Example 1: Basic Execution

.github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

Example 2: Extended Timeout

STARTUP_TIMEOUT=180 VERBOSE=1 \
  .github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

Example 3: Test Specific Version

CROWDSEC_VERSION=v1.5.0 \
  .github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

Example 4: Keep Containers for Debugging

SKIP_CLEANUP=true \
  .github/skills/scripts/skill-runner.sh integration-test-crowdsec-startup

Startup Sequence Verified

1. Phase 1: Container Start (0-5s)

   • Container created and started
   • Entrypoint script execution
   • Environment variable processing

2. Phase 2: LAPI Initialization (5-15s)

   • Database connection established
   • Schema migration/validation
   • Configuration parsing
   • API server binding

3. Phase 3: Bouncer Registration (15-25s)

   • Bouncer discovers LAPI
   • API key generated/validated
   • Initial decision sync
   • Cache population

4. Phase 4: Ready State (25-30s)

   • Health check endpoint responds
   • All components initialized
   • Ready to process requests

Error Handling

Common Errors

Error: Startup timeout exceeded

Solution: Increase STARTUP_TIMEOUT or check container logs for hangs

Error: Database connection failed

Solution: Verify database container is running and accessible

Error: Configuration validation failed

Solution: Check CrowdSec config files for syntax errors

Error: Port already in use

Solution: Stop conflicting services or change port configuration

Debugging

• LAPI Logs: docker logs $(docker ps -q -f name=crowdsec) -f
• Bouncer Logs: docker logs $(docker ps -q -f name=charon-app) | grep crowdsec
• Health Check: curl http://localhost:8080/health
• Database: docker exec crowdsec cscli machines list

Related Skills

• integration-test-crowdsec - Main bouncer tests
• integration-test-crowdsec-decisions - Decision tests
• docker-verify-crowdsec-config - Config validation

Notes

• Execution Time: Medium execution (3-5 minutes)
• Typical Startup: 20-30 seconds for clean start
• Warm Start: 5-10 seconds after restart
• Timeout Buffer: Default timeout includes safety margin
• Container Orchestration: Tests applicable to Kubernetes/Docker Swarm
• Production Ready: Validates production deployment scenarios
• Cleanup: Automatically removes test containers unless SKIP_CLEANUP=true
• Idempotency: Safe to run multiple times consecutively

---

Last Updated: 2025-12-20 Maintained by: Charon Project Team Source: scripts/crowdsec_startup_test.sh