Local Setup

Run Weam AI on your local machine for development, testing, or evaluation using Docker.

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.

Domain & Proxy Setup (RECOMMENDED)

To keep all your AI applications and services under one unified domain, and prevent conflicts when running multiple apps or services, Weam uses an NGINX proxy setup.

• Why? Having everything under a single (local) domain is robust and scalable if you ever run multiple apps/services, and avoids port conflicts.
• We strongly recommend using a custom local domain (such as https://weam.local), rather than only using ‘localhost:3000’.
• You can use any custom local domain but it must start with https:// to ensure security and compatibility.

Mandatory Step Before nginx Proxy Setup:

1. Edit your .env file and set:

NEXT_PUBLIC_DOMAIN_URL=https://weam.local

(You may use another custom local domain, but it must start with https://.)

2. Edit your .env file and set:

bash nginx_setup.sh

Note: Skipping this setup or using only localhost:3000 may cause problems if running multiple apps/services or using browser API features that require HTTPS domains.

Installation Steps

macOS/Linux

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. Edit .env for Domain

   Open your .env file and set your local domain (recommended: https://weam.local):

   NEXT_PUBLIC_DOMAIN_URL=https://weam.local
   

   You can use any custom local domain, but it must start with https://.

3. Build and Start Services

   Use the following commands to build and run the project:

   bash build.sh
   docker compose up --build
   

4. Run Proxy Setup (NGINX)

   After the above services are running, start the NGINX proxy:

   bash nginx_setup.sh
   

5. Access Application

   Open your browser and navigate to:

   • Main Application: https://weam.local
   • Registration: https://weam.local/register
   • Login: https://weam.local/login

   If you used a different domain, replace weam.local with your chosen value.

Service Ports

Service	Port	URL
Frontend (Next.js)	3000	http://localhost:3000
Backend (Node.js)	4050	http://localhost:4050
MongoDB	27017	Internal only
Redis	6379	Internal only
Qdrant (Vector DB)	6333	http://localhost:6333
MinIO (File Storage)	9000	http://localhost:9000

Troubleshooting

macOS/Linux

Build Failures

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

Permission Errors

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)

Out of Memory

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

Pull access denied Error

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.