Skip to main content
Minimum configuration: To ensure smooth execution, your system must meet these minimum requirements:
  • RAM: 8 GB
  • CPU: Quad-core (4 cores)
  • Storage: 10GB free disk space
  • Docker Desktop installed
  • Git installed
Operating Systems
  • MacOS (Intel or Apple Silicon)
  • Linux (Ubuntu 20.04+ recommended)
  • Windows 10/11 with WSL2
Based on our testing, the app runs best with this configuration, providing a smooth and responsive experience.⚠️ Using lower specs may lead to noticeable latency or performance issues.If you’re experiencing performance issues, consider closing background apps or upgrading system resources.

​
Installation Steps

  • macOS/Linux
  • Windows (WSL2)
1

Clone Repository

Clone the project from GitHub and create your environment file:
git clone https://github.com/weam-ai/weam.git
cd weam
cp .env.example .env
2

Build and Start Services

Use the following commands to build and run the project:
bash build.sh
docker compose up --build
This will:
  • Build all necessary Docker images
  • Start backend, frontend, and supporting services
Ensure Docker and Docker Compose are installed before proceeding.
3

Access Application

Open your browser and navigate to:

​
Service Ports

ServicePortURL
Frontend (Next.js)3000http://localhost:3000
Backend (Node.js)4050http://localhost:4050
MongoDB27017Internal only
Redis6379Internal only
Qdrant (Vector DB)6333http://localhost:6333
MinIO (File Storage)9000http://localhost:9000

​
Troubleshooting

  • macOS/Linux
  • Windows (WSL2)
Common causes:
  • Docker doesn’t have enough memory allocated (8GB minimum)
  • Ports 3000 and 4050 are already in use
  • Docker daemon not running
Solutions:
  • Increase Docker’s memory limit in Docker Desktop settings
  • Stop other services using those ports: sudo lsof -i :3000
  • Start Docker Desktop and wait for it to fully load
On Linux:
  • Add your user to the docker group: sudo usermod -aG docker $USER
  • Restart your terminal session after adding to the docker group
  • Try: newgrp docker to apply group changes immediately
On macOS:
  • Ensure Docker Desktop has proper permissions
  • Try running with sudo if needed (not recommended for regular use)
Solutions:
  • Close other applications to free up RAM
  • Increase Docker’s memory limit in Docker Desktop settings
  • Consider upgrading system RAM if consistently running into issues
  • Use docker system prune to clean up unused containers and images
Error
  • Error response from daemon: pull access denied for <image-name>, repository does not exist or may require 'docker login'
Solutions
  • Clear Docker Build Cache and Rebuild
  • Remove all Docker build cache and images
  • Run the following command to clear all cached layers and build data: docker builder prune -a -f
  • This command removes all unused build cache and intermediate images, ensuring a clean environment.
  • Rebuild the application from scratch

​
Key Reminders

  • Always save .sh files with LF line endings on Windows
  • Use Ubuntu (WSL2) terminal for Windows development
  • The first build takes longer due to image downloads and compilation

​
Advanced Configuration

Mandatory Step: Weam AI requires OpenAI API access for core functionality including RAG processing, document analysis, and web scraping. The application will not work properly without an OpenAI API key.
⚠️ IMPORTANT DATABASE WARNING:If you run the command docker compose down -v, your DATABASE will be RESET and all data will be permanently lost.Always take a backup of your database before running this command:
# Create database backup first
docker exec weam-mongodb mongodump --out /tmp/backup

# Copy backup to host system
docker cp weam-mongodb:/tmp/backup ./mongodb-backup

# Only then run the reset command if needed
docker compose down -v
The -v flag removes all volumes including your database data. Use this command only when you want a complete fresh start.
Need help? Reach out via the GitHub issues or Discord Community for faster response.
⌘I