BlucaScan Documentation

Deployment Guide

Deploy BlucaScan using Docker Compose with BluBlast integration. This guide covers the complete setup process, environment configuration, and production deployment best practices.

Docker Compose Configuration

Complete docker-compose.yaml setup with BluBlast integration

services:
  bluBlast:
    image: bluBlast/bluBlast-debian:1.4.3_base
    container_name: bluBlast
    restart: always
    volumes:
      - ./signatures-db:/var/lib/bluBlast:rw
      - ./scan-dir:/scandir:rw
    networks:
      - bluca-scan-net

  bluca-scan:
    image: "ghcr.io/chriseteka/bluca-scan/bluca-scan:${API_TAG}"
    container_name: bluca-scan
    restart: on-failure
    ports:
      - "7300:7300"
    env_file:
      - ./.env
    volumes:
      - ./service-logs:/workspace/logs
    depends_on:
      bluBlast:
        condition: service_healthy
    links:
      - bluBlast
    healthcheck:
      test: ["CMD", "/workspace/health-check"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s
    environment:
      THC_PORT: 7300
      THC_PATH: /api/bluca-scan/actuator/health
      BLUCA_SCAN_HOST: bluBlast
    networks:
      - bluca-scan-net

networks:
  bluca-scan-net:
    external: true

Service Components

BluBlast

Antivirus engine for malware detection and file scanning

BlucaScan API

Main service handling file uploads, scanning coordination, and transfers

Health Checks

Automated health monitoring and service recovery

Volume Mounts

./signatures-db

BluBlast virus signature database storage

./scan-dir

Temporary directory for file scanning operations

./service-logs

Application logs and audit trails

Environment Configuration (.env)

Complete environment variable setup

# API Configuration
API_TAG=1

# Webhook Configuration
BLUCA_SCAN_WEBHOOK_ENABLED=true
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_URL=https://HOST/PATH
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_METHOD=POST
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_MAX_RETRIES=3
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_RETRY_DELAY_IN_MILLIS=10000

# Webhook Authentication
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_AUTH_ENABLED=true
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_BASIC_AUTH_USERNAME=username
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_BASIC_AUTH_PASSWORD=password
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_API_KEY=api-key
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_API_KEY_HEADER_NAME=X-BlucaScan-Event-Endpoint-ApiKey
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_API_KEY_REQUEST_BODY_FIELD_NAME=fieldName

# Data Integrity
BLUCA_SCAN_WEBHOOK_EVENT_VALIDATION_ENABLED=true
BLUCA_SCAN_WEBHOOK_EVENT_HMAC_HEADER_NAME=X-BlucaScan-Event-Signature
BLUCA_SCAN_WEBHOOK_EVENT_HMAC_ALGORITHM=HMAC_SHA256

# File Processing
BLUCA_SCAN_SMALL_SIZED_FILE_THRESHOLD=10MB
BLUCA_SCAN_LARGE_SIZED_FILE_THRESHOLD=100MB
BLUCA_SCAN_ENABLE_STRICT_FILE_TYPE_CHECK=true
BLUCA_SCAN_ENABLE_LENIENT_ON_DEMAND_SCAN=true
BLUCA_SCAN_SUPPORTED_MEDIA_TYPES='text/plain','application/pdf','image/png','image/jpeg','image/gif','application/zip'

Environment Variables Reference

Complete list of configuration options

Variable	Required	Default	Description
API_TAG	Required	1	API version tag for OpenAPI specification
BLUCA_SCAN_WEBHOOK_ENABLED	Optional	true	Enable or disable webhook functionality
BLUCA_SCAN_WEBHOOK_EVENT_ENDPOINT_URL	Required	-	URL for webhook event notifications
BLUCA_SCAN_SMALL_SIZED_FILE_THRESHOLD	Optional	5MB	Threshold for small file processing
BLUCA_SCAN_LARGE_SIZED_FILE_THRESHOLD	Optional	100MB	Threshold for large file background processing
BLUCA_SCAN_SUPPORTED_MEDIA_TYPES	Optional	See config	Comma-separated list of supported MIME types

Deployment Steps

Step-by-step deployment process

Create Network

docker network create bluca-scan-net

Create the external network for service communication

Prepare Directories

mkdir -p signatures-db scan-dir service-logs
chmod 755 signatures-db scan-dir service-logs

Create required directories with proper permissions

Configure Environment

cp .env.example .env && nano .env

Copy and customize the environment configuration

Deploy Services

docker-compose up -d

Start all services in detached mode

Verify Deployment

docker-compose ps 
 curl http://localhost:7300/api/bluca-scan/actuator/health

Check service status and health endpoints

Important Notes:

• Ensure directories have proper read/write permissions
• BluBlast requires time to download virus signatures on first start
• Monitor logs during initial deployment for any issues

Production Tips:

• Use a reverse proxy (Nginx) for SSL termination
• Set up log rotation for service logs
• Configure resource limits in docker-compose.yaml

Production Considerations

Best practices for production deployment

Security

• Use strong passwords and API keys
• Enable HTTPS with proper SSL certificates
• Restrict network access with firewall rules
• Regularly update container images
• Monitor for security vulnerabilities

Performance

• Configure appropriate resource limits
• Set up log rotation and cleanup
• Monitor disk space for scan directories
• Use SSD storage for better I/O performance
• Consider horizontal scaling for high loads

Monitoring

• Set up health check monitoring
• Configure alerting for service failures
• Monitor webhook delivery success rates
• Track file processing metrics
• Set up centralized logging

Automation

• Integrate with CI/CD pipelines
• Use systemd for container lifecycle management
• Automate backup of configuration and logs
• Set up automated security updates
• Configure service discovery if using orchestration