Skip to main content

​
Installation

BOOM runs on macOS and Linux. Follow the instructions below to set up your development environment.
If you’re on Windows, you must use WSL2 (Windows Subsystem for Linux) and install a Linux distribution like Ubuntu 24.04.

​
System requirements

Before installing BOOM, ensure you have the following prerequisites:
  • Docker and docker compose: Used to run MongoDB, Redis/Valkey, and Kafka
  • Rust >= 1.55.0: Systems programming language used by BOOM
  • tar: Used to extract archived alerts for testing
  • libssl, libsasl2: Required for Rust crates that depend on native libraries for secure connections and authentication
  • Kafka CLI tools: Available with brew install kafka on macOS

​
Installation by platform

​
Docker

On macOS we recommend using Docker Desktop to install Docker.
1

Download Docker Desktop

Visit the Docker Desktop website and download the installer for macOS.
2

Install and create account

Follow the installation instructions. The website will ask you to “choose a plan”, but you just need to create a free account that offers all the features you’ll need.
3

Verify installation

Open a terminal and verify the installation:
docker --version
docker compose version

​
Rust

You can install Rust using either rustup (recommended) or Homebrew.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
We recommend using rustup, as it allows you to easily switch between different versions of Rust and keep your installation up to date.
Verify the installation:
rustc --version
cargo --version

​
System packages

System packages are essential for compiling and linking some Rust crates. Most should come with macOS by default, but if you encounter compilation errors, install them with Homebrew:
brew install openssl@3 cyrus-sasl gnu-tar

​
Kafka CLI tools

Install Kafka command-line tools:
brew install kafka

​
Clone the repository

Clone the BOOM repository from GitHub: 
git clone https://github.com/boom-astro/boom.git
cd boom

​
Environment configuration

BOOM uses environment variables for sensitive configuration like passwords and API keys.
1

Copy the example environment file

cp .env.example .env
2

Edit configuration (optional)

For local development, the defaults in .env.example work fine. For production, update the following:
  • BOOM_DATABASE__PASSWORD: MongoDB admin password
  • BOOM_API__AUTH__SECRET_KEY: JWT secret key (at least 32 characters)
  • BOOM_API__AUTH__ADMIN_PASSWORD: Admin API password
  • KAFKA_ADMIN_PASSWORD: Kafka admin password
  • KAFKA_READONLY_PASSWORD: Kafka read-only user password
Do not commit .env to Git or use the example values in production. Always use strong, unique passwords for production deployments.

​
Email configuration (optional)

To send emails for notifications and Babamul account activation codes, configure the email-related environment variables in .env: 
EMAIL_ENABLED=true
SMTP_SERVER=smtp.example.com
SMTP_USERNAME=boom_service
SMTP_PASSWORD=your_smtp_password
SMTP_FROM_ADDRESS=[email protected]
If email is not configured or disabled, Babamul activation codes will be printed to the console logs instead.

​
Start services

Launch the required services using Docker Compose: 
docker compose --profile api up -d
This starts:
  • Valkey (Redis fork): In-memory cache and task queue
  • MongoDB: Document database for alert storage
  • Kafka: Message broker for alert streaming
  • BOOM API: HTTP API server (in development)
  • Prometheus: Metrics and monitoring
This may take a couple of minutes the first time you run it, as Docker needs to download the images for each service.
Verify the containers are running: 
docker ps
You should see containers for mongo, valkey, broker (Kafka), and other services.

​
Build BOOM

Build the Rust binaries: 
cargo build --release
The --release flag enables optimizations for better performance. The first build may take several minutes as Cargo compiles all dependencies.

​
Verify installation

Verify BOOM is ready by checking the available binaries: 
# List available BOOM binaries
ls -la target/release/
You should see binaries including:
  • kafka_consumer
  • kafka_producer
  • scheduler

​
Next steps

Quick start guide

Now that BOOM is installed, follow the quickstart guide to process your first alerts

​
Troubleshooting

​
Compilation errors

If you encounter compilation errors related to missing libraries:
  • macOS: Install system packages with brew install openssl@3 cyrus-sasl gnu-tar
  • Linux: Ensure you have libssl-dev and libsasl2-dev installed

​
Docker issues

If Docker Compose fails to start:
  1. Ensure Docker is running: docker info
  2. Check container logs: docker compose logs
  3. Verify port availability: Ports 4000, 6379, 9092, 27017, and 9090 must be available

​
Permission errors

If you encounter permission errors with Docker on Linux, add your user to the docker group: 
sudo usermod -aG docker $USER
newgrp docker

Build docs developers (and LLMs) love

Get started for freeTalk to us