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

<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.
</Tip>

## Installation Steps

<Tabs>
  <Tab title="macOS/Linux">
    <Steps>
      <Step title="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
        ```
      </Step>

      <Step title="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://`.
      </Step>

      <Step title="Build and Start Services">
        Use the following commands to build and run the project:

        ```bash theme={null}
        bash build.sh
        docker compose up --build
        ```
      </Step>

      <Step title="Run Proxy Setup (NGINX)">
        After the above services are running, start the NGINX proxy:

        ```bash theme={null}
        bash nginx_setup.sh
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows (WSL2)">
    <Steps>
      <Step title="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**)
      </Step>

      <Step title="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.
      </Step>

      <Step title="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`)
      </Step>

      <Step title="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
        ```
      </Step>

      <Step title="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://`.
      </Step>

      <Step title="Set Execute Permissions">
        Make script executable:

        ```bash theme={null}
        chmod +x winbuild.sh
        ```

        Run it:

        ```bash theme={null}
        bash winbuild.sh
        ```
      </Step>

      <Step title="Start Services">
        Start the environment:

        ```bash theme={null}
        docker compose up --build
        ```
      </Step>

      <Step title="Run Proxy Setup (NGINX)">
        After the above services are running, start the NGINX proxy:

        ```bash theme={null}
        bash nginx_setup.sh
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="macOS/Linux">
    <AccordionGroup>
      <Accordion title="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>

      <Accordion title="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>

      <Accordion title="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>

      <Accordion title="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
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Windows (WSL2)">
    <AccordionGroup>
      <Accordion title="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>

      <Accordion title="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>

      <Accordion title="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
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

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

<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.
</Warning>

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