Mongoose server Deployment Guide¶

Introduction¶

This document provides guidance on deploying Mongoose server in various environments. It covers deployment considerations, performance tuning, and best practices to ensure optimal operation of Mongoose server applications.

Deployment Models¶

Mongoose server can be deployed in several ways, depending on the requirements of your application:

Standalone Application¶

Mongoose server can be deployed as a standalone Java application. This is the simplest deployment model and is suitable for many use cases.

Configuration:¶

// Load configuration from a file
MongooseServer server = MongooseServer.bootServer(logRecordListener);

// Or programmatically
MongooseServerConfig mongooseServerConfig = new MongooseServerConfig();
// Configure mongooseServerConfig
MongooseServer server = MongooseServer.bootServer(mongooseServerConfig, logRecordListener);

Embedded in Another Application¶

Mongoose server can be embedded within another Java application, such as a Spring Boot application or a web server.

Configuration:¶

// Create and configure the server
MongooseServerConfig mongooseServerConfig = new MongooseServerConfig();
// Configure mongooseServerConfig
MongooseServer server = new MongooseServer(mongooseServerConfig);

// Register components
server.registerEventSource("source1", eventSource);
server.addEventProcessor("processor1", "group1", idleStrategy, () -> eventProcessor);

// Initialize and start
server.init();
server.start();

Containerized Deployment¶

Mongoose server can be deployed in containers such as Docker, which provides isolation and portability.

Container requirements¶

This candidate targets Java 21. Package your application entry point, processor classes, plugins and runtime dependencies together using your application's build. Mongoose is a library; there is no universal fluxtion-server.jar to copy into an image.

For an executable application jar that calls MongooseServer.bootServer(), a launch command can be:

java -Xms1g -Xmx1g -DmongooseServer.config.file=/app/config/server.yaml -jar /app/application.jar

The system property belongs before -jar. Supply the YAML and plugin configuration appropriate to your application. Set the supervisor's termination grace period to allow the configured shutdown budget and any operational response to an incomplete result. Monitor StopResult; a bounded stop can return while a callback remains blocked.

Cloud Deployment¶

Mongoose server can be deployed to cloud environments such as AWS, Azure, or Google Cloud Platform.

Considerations:¶

Use managed services for monitoring and logging
Configure auto-scaling based on load
Use cloud-native storage for persistence
Implement proper security measures

Performance Considerations¶

Memory Configuration¶

Proper memory configuration is essential for optimal performance:

-Xmx<size>  # Maximum heap size
-Xms<size>  # Initial heap size
-XX:MaxMetaspaceSize=<size>  # Maximum metaspace size

Recommended settings: - Set -Xms and -Xmx to the same value to avoid heap resizing - Monitor memory usage and adjust as needed - Consider using G1GC for large heaps: -XX:+UseG1GC

Thread Configuration¶

Mongoose server uses a threading model based on agents. Configure threads appropriately:

Use MongooseServerConfig.agentThreads / ThreadConfig to choose each agent's idle strategy and optional core id. For low latency, busy spin needs sufficient dedicated CPU capacity. Backoff/yield/sleep trade wake-up latency for idle CPU use; measure your actual workload rather than choosing a strategy from its name alone. See thread configuration.

Queues and overload¶

Monitor queue depth and drops. The current publisher retries a full queue for about 10 ms and then drops that queue's copy. Increasing capacity absorbs bursts but cannot make a sustained overload lossless. See event flow.

Shutdown and remaining resources¶

Use shutdown() and inspect StopResult. Processor groups must close before their remaining service dependencies are stopped. Unresolved capture resources or failed callbacks can leave the server STOPPING; another shutdown attempt resumes unfinished phases. See the shutdown sequence.

Availability and recovery¶

A Mongoose server is one JVM. What it supports today for keeping a deployment available:

Supervised restart. Run the server under a process supervisor (systemd, a Kubernetes Deployment, a container restart policy) so a failed JVM is restarted. Make startup fail fast when a critical service, feed or processor does not start (see the operations runbook), so a bad deployment exits instead of running half-started.
Health checks. MongooseHealthService aggregates the built-in and your own checks; expose it to your supervisor or load balancer for liveness and readiness.
Rebuilding state. Mongoose does not replicate or snapshot processor state. Rebuild it on restart from your own source of truth (a database, a venue's state, an event log you keep), or replay a recorded run into a processor (record and replay) to reproduce or verify state.
Running more than one instance. You can run several independent servers, each with its own feeds and processors. Mongoose does not coordinate them: partitioning the work, electing an active instance and moving load are up to your deployment.

Not yet supported (direction)¶

The following are directions, not features. Do not plan a deployment that depends on them:

Clustering: active-passive or active-active groups of servers managed by Mongoose.
State replication: Mongoose-managed replication or snapshots of processor state between instances.
Failover: Mongoose-managed detection of a failed instance and hand-over of its work.

Monitoring and Observability¶

Metrics Collection¶

Collect metrics to monitor the health and performance of your Mongoose server:

JVM Metrics: Heap usage, GC activity, thread count
Application Metrics: Event throughput, processing latency, queue sizes
System Metrics: CPU usage, memory usage, disk I/O, network I/O

Logging¶

Configure appropriate logging to aid in troubleshooting:

// Set log level for event processors
eventProcessor.setAuditLogLevel(EventLogControlEvent.LogLevel.INFO);

Recommendations: - Use structured logging for easier parsing - Configure appropriate log levels for different components - Rotate logs to manage disk space

Tracing across processes¶

Mongoose has no built-in distributed tracing (trace or span propagation, Jaeger/Zipkin export); it is not yet supported. Within one server the audit log records each event cycle. For work that leaves the process, carry your own correlation id on the events you publish and log it at each boundary.

Security Considerations¶

Authentication and Authorization¶

Implement proper authentication and authorization:

API Security: Secure admin APIs with authentication
Role-Based Access: Restrict access based on roles
Secure Communication: Use TLS for communication between components

Data Protection¶

Protect sensitive data:

Encryption: Encrypt sensitive data at rest and in transit
Data Masking: Mask sensitive data in logs
Access Control: Restrict access to sensitive data

Network Security¶

Secure the network:

Firewalls: Restrict network access
VPNs: Use VPNs for secure communication
Network Segmentation: Isolate components in different network segments

Configuration Management¶

Configuration Files¶

Manage configuration files effectively:

Version Control: Store configuration files in version control
Environment-Specific Configs: Use different configurations for different environments
Configuration Validation: Validate configuration before deployment

Dynamic Configuration¶

Change a running processor's configuration by delivering the change as an event on the processor's own agent thread: publish it on a feed the processor subscribes to, or register an admin command from the processor (how to write an admin command), which Mongoose runs in the processor's event cycle. Never call a running processor's onEvent from another thread: a processor is not thread-safe, and the call would race its agent thread.

Deployment Checklist¶

Before deploying Mongoose server to production, ensure:

Performance Testing: Test performance under expected load
Security Review: Review security measures
Monitoring Setup: Set up monitoring and alerting
Backup Strategy: Implement backup and recovery procedures
Documentation: Document deployment procedures and configurations
Rollback Plan: Prepare a rollback plan in case of issues