Knowledge Hub

Prerequisites

Before getting started with OpenFrame, ensure your development environment meets the following requirements.

System Requirements

Minimum Hardware Requirements

Operating System Support

OpenFrame supports development on:

• Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+)
• macOS (10.15+)
• Windows (Windows 10/11 with WSL2 recommended)

Required Software

Java Development

Install Java 21:

# Ubuntu/Debian
sudo apt update
sudo apt install openjdk-21-jdk

# macOS with Homebrew
brew install openjdk@21

# Windows (download from Oracle or use Chocolatey)
choco install openjdk21

Verify Java installation:

java -version
# Should show: openjdk version "21.x.x"

mvn -version
# Should show: Apache Maven 3.8.x or higher

Node.js Development

Install Node.js:

# Ubuntu/Debian - via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS with Homebrew
brew install node

# Windows - download from nodejs.org or use Chocolatey
choco install nodejs

Verify Node.js installation:

node --version
# Should show: v18.x.x or higher

npm --version
# Should show: 9.x.x or higher

Database Systems

OpenFrame requires several database systems for different purposes:

Message Brokers

Development Tools

Environment Variables

Set the following environment variables for development:

Database Configuration

# MongoDB
export MONGODB_URI="mongodb://localhost:27017/openframe"
export MONGODB_DATABASE="openframe"

# Cassandra
export CASSANDRA_CONTACT_POINTS="localhost:9042"
export CASSANDRA_KEYSPACE="openframe_logs"

# Redis
export REDIS_HOST="localhost"
export REDIS_PORT="6379"

# Apache Pinot
export PINOT_CONTROLLER_URL="http://localhost:9000"
export PINOT_BROKER_URL="http://localhost:8000"

Message Brokers

# Kafka
export KAFKA_BOOTSTRAP_SERVERS="localhost:9092"
export KAFKA_GROUP_ID="openframe-dev"

# NATS
export NATS_SERVERS="nats://localhost:4222"
export NATS_CLUSTER_ID="openframe-cluster"

Application Configuration

# OpenFrame Configuration
export OPENFRAME_PROFILE="development"
export OPENFRAME_CONFIG_SERVER="http://localhost:8888"

# Security
export JWT_SECRET="your-jwt-secret-key-here"
export OAUTH2_CLIENT_SECRET="your-oauth2-client-secret"

# AI Integration
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Account Requirements

Required Accounts

While OpenFrame is open-source, you may need accounts for:

• Anthropic (for Claude AI integration) - Get API key
• OpenAI (for GPT integration) - Get API key
• GitHub (for source code access) - Free account

Optional Third-party Integrations

Depending on your MSP needs:

• Google Workspace (for SSO)
• Microsoft Azure AD (for SSO)
• Slack (for notifications)
• Various RMM/PSA tools (TacticalRMM, ConnectWise, etc.)

Network Requirements

Firewall Considerations

Ensure the following ports are accessible:

Database Ports

Message Broker Ports

Verification Commands

Run these commands to verify your environment is ready:

Check Java and Maven

java -version
mvn -version

Check Node.js

node --version
npm --version

Check Docker

docker --version
docker compose version

Check Git

git --version

Test Database Connections

# MongoDB (if running locally)
mongosh --eval "db.runCommand('ping')"

# Redis (if running locally)
redis-cli ping

Quick Setup with Docker

For development, you can start the required databases using Docker Compose:

# Create a docker-compose.yml for development dependencies
curl -o docker-compose.dev.yml https://raw.githubusercontent.com/flamingo-stack/openframe-oss-tenant/main/docker-compose.dev.yml

# Start development databases
docker compose -f docker-compose.dev.yml up -d

This will start MongoDB, Redis, Kafka, and other required services in development mode.

Next Steps

Once your environment meets these prerequisites:

1. Quick Start Guide - Get OpenFrame running quickly
2. First Steps Guide - Explore the platform features

Troubleshooting

Common Issues

Java Version Conflicts:

# Check all Java versions
java -version
javac -version
echo `$JAVA_HOME`

Port Conflicts:

# Check what's running on OpenFrame ports
netstat -tulpn | grep :8080
lsof -i :8080  # macOS

Docker Issues:

# Restart Docker service
sudo systemctl restart docker  # Linux
# Or restart Docker Desktop on macOS/Windows

Getting Help

If you encounter issues:

• Join the OpenMSP Slack Community
• Check the platform documentation for environment-specific guides

Ready to proceed? Continue with the Quick Start Guide to get OpenFrame running.