Installation
Install Beever Atlas using Docker Compose for a complete, production-ready stack.
Prerequisites
Before installing Beever Atlas, ensure you have:
- Docker 20.10+ and Docker Compose 2.0+
- Python 3.11+ (for local development)
- Node.js 20+ (for local development)
- uv (Python package manager, for local development)
- Google API Key for Gemini (required for all LLM operations)
- Jina API Key for embeddings (required)
Need API keys? Both Google and Jina offer free tiers suitable for development:
- Get a Google API Key — Free tier available
- Get a Jina API Key — Free tier available
Quick Install (Docker Compose)
Step 1: Clone the Repository
git clone https://github.com/beever-ai/beever-atlas.git
cd beever-atlasStep 2: Configure Environment
Copy the example environment file:
cp .env.example .envEdit .env with your API keys. The minimum required configuration:
# Required - LLM and Embeddings
GOOGLE_API_KEY=your_google_api_key_here
JINA_API_KEY=your_jina_api_key_here
# Optional - Development defaults
BEEVER_API_URL=http://localhost:8000
CORS_ORIGINS=http://localhost:5173,http://localhost:3000Step 3: Configure Database Connections
The default .env.example includes preconfigured values for Docker Compose:
# These are already set for Docker Compose
WEAVIATE_URL=http://localhost:8080
NEO4J_URI=bolt://localhost:7687
NEO4J_AUTH=neo4j/beever_atlas_dev
MONGODB_URI=mongodb://localhost:27017/beever_atlas
REDIS_URL=redis://localhost:6379Step 4: Start Services
docker compose up -dThis starts all services:
- beever-atlas (Python Backend) — Port 8000
- web (React Frontend) — Port 3000
- bot (Bot Service) — Port 3001
- weaviate (Semantic Memory) — Port 8080
- neo4j (Graph Memory) — Ports 7474 (HTTP), 7687 (Bolt)
- mongodb (State & Cache) — Port 27017
- redis (Sessions) — Port 6380
First run takes 2–3 minutes as Docker builds images and databases initialize. Check status with docker compose ps.
Step 5: Verify Installation
Check that all services are healthy:
docker compose psAll services should show "healthy" status. Test the backend:
curl http://localhost:8000/api/healthExpected response:
{
"status": "healthy",
"components": {
"weaviate": {"status": "up"},
"neo4j": {"status": "up"},
"mongodb": {"status": "up"},
"redis": {"status": "up"}
}
}Environment Variables
Core Application
Prop
Type
Databases
Prop
Type
LLM & Embeddings
Prop
Type
Pipeline & Quality Gates
Prop
Type
Integrations
Prop
Type
Security
Prop
Type
Generate secure keys:
# Generate credential master key
openssl rand -hex 32
# Generate bridge API key
openssl rand -hex 16Alternative Graph Backend: NebulaGraph
Atlas supports NebulaGraph as an alternative to Neo4j:
# Install NebulaGraph dependencies
pip install ".[nebula]"
# Configure in .env
GRAPH_BACKEND=nebula
NEBULA_HOSTS=127.0.0.1:9669
NEBULA_USER=root
NEBULA_PASSWORD=nebula
NEBULA_SPACE=beever_atlas
# Use NebulaGraph Docker Compose file
docker compose -f docker-compose.nebula.yml up -dLocal Development (Without Docker)
For faster iteration, run services directly:
Start Databases Only
docker compose up weaviate neo4j mongodb redisBackend
# Install dependencies
uv sync
# Run FastAPI server
uv run uvicorn beever_atlas.server.app:app --reload --port 8000Bot Service
cd bot
npm install
npm run devFrontend
cd web
npm install
npm run dev # Starts at http://localhost:5173Troubleshooting
Port Already in Use
If a port is already in use, edit the ports mapping in docker-compose.yml or stop the conflicting service:
docker compose downDatabase Connection Errors
Ensure databases are healthy:
docker compose logs weaviate
docker compose logs neo4j
docker compose logs mongodbRestart specific services:
docker compose restart weaviate neo4jWeaviate Schema Errors
If you see schema errors on startup, reset Weaviate's data volume:
Warning: This deletes all indexed data and requires re-syncing your channels.
docker compose down -v
docker compose up -dBuild Failures
If Docker build fails, try rebuilding without cache:
docker compose build --no-cache
docker compose up -dWhat's Next?
- Quick Start — Try Atlas with mock mode in 5 minutes
- Slack Setup — Connect your real Slack workspace
- Deployment — Production deployment guide