> ## Documentation Index
> Fetch the complete documentation index at: https://opensource.weam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Setup

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

> [!TIP]
>
> **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.

> [!TIP]
>
> **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**](https://nginx.org/).
>
> * **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**](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:
>
> ```env theme={null}
> 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:
>
> ```env theme={null}
> 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

> [tab] macOS/Linux
>
> **1. Clone Repository**
>
> Clone the project from GitHub and create your environment file:
>
> ```bash theme={null}
> 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`):
>
> ```env theme={null}
> 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 theme={null}
> bash build.sh
> docker compose up --build
> ```
>
> **4. Run Proxy Setup (NGINX)**
>
> After the above services are running, start the NGINX proxy:
>
> ```bash theme={null}
> bash nginx_setup.sh
> ```
>
> **5. Access Application**
>
> Open your browser and navigate to:
>
> * **Main Application:** [https://weam.local](https://weam.local)
> * **Registration:** [https://weam.local/register](https://weam.local/register)
> * **Login:** [https://weam.local/login](https://weam.local/login)
>
> If you used a different domain, replace `weam.local` with your chosen value.

> [tab] Windows (WSL2)
>
> **1. Install Docker Desktop**
>
> [Official Installation Guide](https://docs.docker.com/desktop/setup/install/windows-install/)
>
> **During installation:**
>
> * ✅ Enable **WSL 2 integration**
> * ✅ Choose your preferred Linux distro (e.g., **Ubuntu**)
>
> **2. Install WSL2 with Ubuntu**
>
> Run in **PowerShell (Admin)**:
>
> ```powershell theme={null}
> wsl --install Ubuntu
> ```
>
> This will:
>
> * Enable WSL features
> * Install Ubuntu
> * Set as default
>
> **Restart your PC** after installation.
>
> **3. Configure Line Endings**
>
> ⚠️ `.sh` files with `CRLF` may break in WSL/Linux.
>
> 1. Open folder in **VS Code**
> 2. Bottom right: click `CRLF` → change to `LF`
> 3. Save the file again
> 4. Repeat for all `.sh` files (e.g., `winbuild.sh`, `build.sh`)
>
> **4. Clone Repository**
>
> In **Ubuntu terminal**, clone the project:
>
> ```bash theme={null}
> git clone https://github.com/weam-ai/weam.git
> cd weam
> cp .env.example .env
> ```
>
> Navigate to your project directory:
>
> ```bash theme={null}
> cd /mnt/c/Users/YOUR_USERNAME/path/to/your/project
> ```
>
> **5. Edit .env for Domain**
>
> Open your `.env` file and **set your local domain** (recommended: `https://weam.local`):
>
> ```env theme={null}
> NEXT_PUBLIC_DOMAIN_URL=https://weam.local
> ```
>
> You can use any custom local domain, but it must start with `https://`.
>
> **6. Set Execute Permissions**
>
> Make script executable:
>
> ```bash theme={null}
> chmod +x winbuild.sh
> ```
>
> Run it:
>
> ```bash theme={null}
> bash winbuild.sh
> ```
>
> **7. Start Services**
>
> Start the environment:
>
> ```bash theme={null}
> docker compose up --build
> ```
>
> **8. Run Proxy Setup (NGINX)**
>
> After the above services are running, start the NGINX proxy:
>
> ```bash theme={null}
> bash nginx_setup.sh
> ```
>
> **9. Access Application**
>
> Open your browser and navigate to:
>
> * **Main Application:** [https://weam.local](https://weam.local)
> * **Registration:** [https://weam.local/register](https://weam.local/register)
> * **Login:** [https://weam.local/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](http://localhost:3000) |
| **Backend (Node.js)** | 4050 | [http://localhost:4050](http://localhost:4050) |
| **MongoDB** | 27017 | Internal only |
| **Redis** | 6379 | Internal only |
| **Qdrant (Vector DB)** | 6333 | [http://localhost:6333](http://localhost:6333) |
| **MinIO (File Storage)** | 9000 | [http://localhost:9000](http://localhost:9000) |

## Troubleshooting

> [tab] macOS/Linux
>
> > [accordion] 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
>
> > [accordion] 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)
>
> > [accordion] 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
>
> > [accordion] 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

> [tab] Windows (WSL2)
>
> > [accordion] WSL2 Issues
> >
> > **Common problems:**
> >
> > * WSL2 not properly installed or configured
> > * Docker Desktop not integrated with WSL2
> > * Line ending issues with shell scripts
> >
> > **Solutions:**
> >
> > * Verify WSL2: `wsl --list --verbose`
> > * Enable WSL2 integration in Docker Desktop settings
> > * Convert line endings: `dos2unix build.sh winbuild.sh`
> > * Restart Docker Desktop after enabling WSL2 integration
>
> > [accordion] Path and Permission Issues
> >
> > **Windows-specific fixes:**
> >
> > * Use Ubuntu terminal, not PowerShell or Command Prompt
> > * Navigate using `/mnt/c/` paths for Windows drives
> > * Set execute permissions: `chmod +x *.sh`
> > * Ensure you're in the correct project directory
>
> > [accordion] Docker Desktop Problems
> >
> > **Solutions:**
> >
> > * Ensure Docker Desktop is running before commands
> > * Check WSL2 integration is enabled in Docker settings
> > * Restart Docker Desktop if containers fail to start
> > * Verify virtualization is enabled in BIOS

## 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

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **⚠️ 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:**
>
> ```bash theme={null}
> # 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.

> [!NOTE]
>
> **Need help?** Reach out via the [GitHub issues](https://github.com/weam-ai/weam/issues) or [Discord Community](https://discord.com) for faster response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.