Installation
This guide covers different ways to install and run Almanac locally, from native development to Docker containers.
Prerequisites
Node.js >= 24.0.0
pnpm >= 8.0.0
Docker Desktop (or Docker Engine + Docker Compose)
2GB RAM minimum (8GB+ recommended for large datasets)
1GB disk space (more for large document collections)
Quick Start (Recommended)
The fastest way to get started:
# Clone repository
git clone https://github.com/tryprotege/almanac.git
cd almanac
# Install dependencies
pnpm install
# Configure environment
cd packages/server
cp .env.example .env
cd ../..Edit packages/server/.env with your LLM API key and settings:
Required: Set your LLM_API_KEY and configure model settings based on your provider.
This will:
Start Docker containers for databases (MongoDB, Redis, Qdrant, Memgraph)
Start backend server locally (port 3000)
Start frontend UI locally (port 5173)
Open http://localhost:5173 to access the UI.
Installation Options
Option 1: Local Development (Recommended)
Run databases in Docker, applications locally for fastest development:
1. Install Dependencies
2. Start Database Services
Expected output:
3. Configure Environment
Edit .env with your LLM API key and settings:
Required: Set your LLM_API_KEY and configure model settings based on your provider.
Optional: Configure reranker settings if needed. The infrastructure services (MongoDB, Redis, etc.) are pre-configured in docker-compose.yml with default settings.
4. Start Application
Server will start on http://localhost:3000 UI will start on http://localhost:5173
Option 2: Full Docker Setup
Run everything in Docker containers:
This starts:
All database services (MongoDB, Redis, Qdrant, Memgraph)
Backend server (production build)
Frontend UI (served by Nginx)
Access at http://localhost (port 80)
Note: This uses production builds without hot reload. The setup is optimized for performance with smaller image sizes and production dependencies only.
Docker Architecture
The application consists of the following services:
Infrastructure Services
MongoDB: Document database (port 27017)
Qdrant: Vector database (ports 6333, 6334)
Memgraph: Graph database (ports 7687, 7444)
Redis: Cache and message queue (port 6379)
Application Services
Server: Node.js backend API (port 3000)
Client: React frontend (port 5173 dev / port 80 prod)
All services communicate through a shared Docker network (almanac-network).
Network Architecture
Database Configuration
All databases are pre-configured in Docker with sensible defaults:
MongoDB
Version: 8.2.2
Port:
27017Default credentials:
Username:
adminPassword:
admin123
Database:
almanac
Redis
Version: Alpine 3.22
Port:
6379Persistence: AOF (Append Only File) enabled
Qdrant
Version: 1.16.0
HTTP Port:
6333gRPC Port:
6334
Memgraph
Version: 3.7.0
Bolt Port:
7687(main connection)HTTP Port:
7444Log Level: WARNING
Useful Docker Commands
Managing Services
Rebuilding Containers
Accessing Containers
Data Management
Data Persistence
When using the full Docker setup, data is stored in the ./data/ directory:
./data/mongodb- MongoDB data./data/qdrant- Vector embeddings./data/memgraph- Graph data./data/redis- Redis cache
Important: Backup this directory to preserve your data.
Port Configuration
Default ports:
Frontend (dev)
5173
Web UI (local dev)
Frontend (prod)
80
Web UI (Docker)
Backend
3000
REST API
MongoDB
27017
Document database
Redis
6379
Cache
Qdrant
6333
Vector database (HTTP)
Qdrant (gRPC)
6334
Vector database (gRPC)
Memgraph
7687
Graph database (Bolt)
Memgraph HTTP
7444
Graph database (HTTP)
To change ports, edit docker-compose.yml or docker-compose.prod.yml and update the corresponding environment variables in packages/server/.env.
System Requirements
Minimum (Development)
CPU: 2 cores
RAM: 8GB
Disk: 10GB SSD
Network: 10 Mbps
Recommended (Production)
CPU: 8 cores (16 for large workloads)
RAM: 32GB (64GB for >1M documents)
Disk: 100GB SSD (more for vectors/graph)
Network: 100 Mbps+
Scaling Guidelines
Small (< 100K documents):
4 CPU cores
16GB RAM
50GB disk
Medium (100K - 1M documents):
8 CPU cores
32GB RAM
200GB disk
Large (1M - 10M documents):
16 CPU cores
64GB RAM
500GB disk
Verification
After installation, verify everything works:
1. Check Services
2. Check Databases
3. Run Test Query
Should return query results (empty if no data indexed yet).
Troubleshooting
Services won't start
Port already in use
Port Conflicts in Docker
If ports are already in use, change them in docker-compose.yml or docker-compose.prod.yml:
Database connection failed
Out of memory
Build Issues (Full Docker)
Upgrading
Minor Updates
Major Updates
Uninstallation
Remove Services
Remove Code
Remove Data
Best Practices
Development Workflow
Use
pnpm startfor the fastest development experience (databases in Docker, apps local)Use full Docker setup (
docker-compose.prod.yml) when you need a production-like environmentNever commit your
.envfile (use.env.exampleas a template)
Working with Docker
Check logs regularly:
docker compose logs -fMonitor resource usage:
docker statsBack up your
./data/directory regularlyUse
docker compose down -vcarefully (it deletes all data)
Next Steps
Configuration Guide - Configure LLM models, API keys, etc.
Quick Start - Connect your first data source
Data Sources - Add more integrations
Architecture - Learn how Almanac works
Support
For issues or questions:
Check service logs:
docker compose logs <service-name>Verify environment configuration in
packages/server/.envReview the main README.md for application-specific setup
Last updated
Was this helpful?