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

# Deploy on Cloud

> [!TIP]
>
> **Minimum cloud configuration:**
>
> * **RAM:** 4 GB (8 GB recommended)
> * **CPU:** 2 vCPUs (4+ vCPUs recommended)
> * **Storage:** 50 GB SSD minimum (100 GB recommended)
> * **OS:** Ubuntu 22.04 LTS
> * **Network:** Public IP with ports 22, 80, 443 open
>
> **Cloud Providers Supported**
>
> * **AWS EC2** (t3.medium or better)
> * **DigitalOcean Droplets** (Basic plan or better)
> * **Other providers** with Ubuntu 22.04 support [**(For localhost, please check local-setup)**](https://opensource.weam.ai/docs/setup/choose-your-setup/local-setup.md)
>
> Based on our testing, these configurations provide optimal performance for WeamAI workloads.
>
> **⚠️ Using lower specs may lead to build failures or performance issues.**
>
> **Domain Requirements:**
>
> * **Development:** No domain needed (uses IP address)
> * **Production:** Custom domain required for HTTPS/SSL

## Deployment Options

> [tab] AWS EC2
>
> **1. Launch EC2 Instance**
>
> Navigate to AWS Console and configure your instance:
>
> **Instance Configuration:**
>
> * **AMI:** Ubuntu Server 22.04 LTS
>
> * **Instance Type:** t3.medium or better
>
> * **Storage:** 50 GB GP2/GP3 SSD minimum
>
> * **Security Group:** Allow SSH (22), HTTP (80), HTTPS (443)
>
> > [!WARNING]
> >
> > For testing, you can allow all inbound traffic, but configure proper security groups for production.
>
> **2. Configure Key Pair**
>
> Create or select an existing key pair for SSH access. Download the `.pem` file and keep it secure.
>
> **3. Add User Data Script**
>
> In **Advanced Details → User Data**, paste the appropriate script:
>
> > [tab] Development (No Domain)
> >
> > ```bash theme={null}
> > #!/bin/bash
> > exec > /home/ubuntu/setup.log 2>&1
> > set -xe
> >
> > # Update system and install dependencies
> > sudo apt update -y
> > sudo apt install -y git curl
> >
> > # Detect public IP
> > PUBLIC_IP=$(curl -s http://checkip.amazonaws.com || curl -s ifconfig.me || hostname -I | awk '{print $1}')
> > echo "Detected Public IP: $PUBLIC_IP"
> >
> > # Clone and setup project
> > sudo git clone https://github.com/weam-ai/weam.git /home/ubuntu/project
> > cd /home/ubuntu/project
> > sudo cp .env.example .env
> >
> > # Configure for development
> > sed -i.bak 's|NEXT_PUBLIC_APP_ENVIRONMENT=production|NEXT_PUBLIC_APP_ENVIRONMENT=development|' .env
> > sudo sed -i "s/localhost/$PUBLIC_IP/g" .env
> >
> > # Install Docker and Docker Compose
> > sudo install -m 0755 -d /etc/apt/keyrings
> > curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
> > sudo chmod a+r /etc/apt/keyrings/docker.gpg
> >
> > echo \
> >   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
> >   https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
> >   | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
> >
> > sudo apt update -y
> > sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
> >
> > sudo systemctl enable docker
> > sudo systemctl start docker
> > sudo chmod 666 /var/run/docker.sock
> >
> > echo "✅ Development setup completed successfully!"
> > ```
>
> > [tab] Production (Domain Required)
> >
> > > [!NOTE]
> > >
> > > Replace `https://yourexampledomain.com` with your actual domain before running this script.
> >
> > ```bash theme={null}
> > #!/bin/bash
> > exec > /home/ubuntu/setup.log 2>&1
> > set -xe
> >
> > # Update system and install dependencies
> > sudo apt update -y
> > sudo apt install -y git nginx
> >
> > # Clone and setup project
> > sudo git clone https://github.com/weam-ai/weam.git /home/ubuntu/project
> > cd /home/ubuntu/project
> > sudo cp .env.example .env
> >
> > # Configure domain (REPLACE WITH YOUR DOMAIN)
> > CUSTOM_DOMAIN="https://yourexampledomain.com"
> >
> > sed -i.bak "s|http://localhost:4050|$CUSTOM_DOMAIN|g" .env
> > sed -i.bak "s|http://localhost:3000|$CUSTOM_DOMAIN|g" .env
> >
> > # Install Docker and Docker Compose
> > sudo install -m 0755 -d /etc/apt/keyrings
> > curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
> > sudo chmod a+r /etc/apt/keyrings/docker.gpg
> >
> > echo \
> >   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
> >   https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
> >   | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
> >
> > sudo apt update -y
> > sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
> >
> > sudo systemctl enable docker
> > sudo systemctl start docker
> > sudo chmod 666 /var/run/docker.sock
> >
> > # Configure Nginx and SSL
> > sudo apt install -y certbot python3-certbot-nginx
> >
> > # Extract domain from URL for nginx configuration
> > DOMAIN=$(echo "$CUSTOM_DOMAIN" | sed -E 's~^https?://~~')
> >
> > # Create Nginx configuration
> > cat <<EOL | sudo tee /etc/nginx/sites-available/yourapp
> > server {
> >     listen 80;
> >     server_name $DOMAIN;
> >
> >     # Frontend
> >     location / {
> >         proxy_pass http://localhost:3000;
> >         proxy_set_header Host \$host;
> >         proxy_set_header X-Real-IP \$remote_addr;
> >         proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
> >         proxy_set_header X-Forwarded-Proto \$scheme;
> >     }
> >
> >     # Node.js API
> >     location /napi/ {
> >         proxy_pass http://localhost:4050/napi/;
> >         proxy_http_version 1.1;
> >         proxy_set_header Host \$host;
> >         proxy_set_header X-Real-IP \$remote_addr;
> >         proxy_set_header Upgrade \$http_upgrade;
> >         proxy_set_header Connection 'upgrade';
> >     }
> >
> >     # MinIO object storage
> >     location /minio/ {
> >         proxy_pass http://localhost:9000/;
> >         proxy_set_header Host \$host;
> >         proxy_set_header X-Real-IP \$remote_addr;
> >     }
> > }
> > EOL
> >
> > # Enable the Nginx configuration
> > sudo ln -sf /etc/nginx/sites-available/yourapp /etc/nginx/sites-enabled/
> > sudo nginx -t && sudo systemctl reload nginx
> >
> > # Configure firewall for web traffic
> > sudo ufw allow 80/tcp
> > sudo ufw allow 443/tcp
> >
> > echo "✅ Production setup completed successfully!"
> > ```
>
> **4. Launch Instance**
>
> Review your configuration and click **Launch Instance**. Wait 5-10 minutes for the initialization script to complete.
>
> **5. Connect and Deploy**
>
> Connect to your instance via SSH:
>
> ```bash theme={null}
> ssh -i your-key.pem ubuntu@<EC2_PUBLIC_IP>
> ```
>
> Navigate to the project directory and start the build:
>
> ```bash theme={null}
> # Check setup completion
> tail -f /home/ubuntu/setup.log
>
> # Navigate to project directory
> cd /home/ubuntu/project
>
> # Build the application (15-20 minutes)
> bash build.sh
>
> # Deploy with Docker Compose
> docker compose up --build
>
> # For background deployment
> docker compose up -d
> ```
>
> **6. Access Application**
>
> **Development Setup:**
>
> ```
> http://<EC2_PUBLIC_IP>:3000/login
> ```
>
> **Production Setup:**
>
> ```
> https://yourexampledomain.com/login
> ```
>
> > [!NOTE]
> >
> > For production, ensure your domain's DNS A record points to your EC2 instance's public IP address.

> [tab] DigitalOcean
>
> **1. Create New Droplet**
>
> Log into DigitalOcean and configure your droplet:
>
> **Droplet Configuration:**
>
> * **Region:** Choose closest to your users
>
> * **Image:** Marketplace → Docker on Ubuntu 22.04
>
> * **Type:** Basic
>
> * **Size:** 2 vCPUs, 4 GB RAM, 50 GB SSD (minimum)
>
> > [!TIP]
> >
> > Using the Docker marketplace image provides one-click Docker setup and saves configuration time.
>
> **2. Authentication Setup**
>
> Choose your preferred method:
>
> * **SSH Key** (recommended for security)
> * **Root Password** (simpler setup)
>
> **3. Add Initialization Script**
>
> Expand **Advanced Options → Add Initialization Script** and paste the appropriate script:
>
> > [tab] Development (No Domain)
> >
> > ```bash theme={null}
> > #!/bin/bash
> > exec > /root/setup.log 2>&1
> > set -xe
> >
> > # Update system and install dependencies
> > sudo apt update -y
> > sudo apt install -y git
> > git --version
> >
> > # Detect public IP (multi-cloud compatible)
> > PUBLIC_IP=$(curl -s http://checkip.amazonaws.com || curl -s ifconfig.me || hostname -I | awk '{print $1}')
> > echo "Detected Public IP: $PUBLIC_IP"
> >
> > # Clone and setup project
> > git clone https://github.com/weam-ai/weam.git /root/project
> > cd /root/project
> > cp .env.example .env
> >
> > # Configure for development mode (no HTTPS required)
> > sed -i.bak 's|NEXT_PUBLIC_APP_ENVIRONMENT=production|NEXT_PUBLIC_APP_ENVIRONMENT=development|' .env
> > sudo sed -i "s/localhost/$PUBLIC_IP/g" .env
> >
> > echo "✅ Development setup completed successfully!"
> > ```
>
> > [tab] Production (Domain Required)
> >
> > > [!NOTE]
> > >
> > > Replace `https://yourexampledomain.com` with your actual domain before using this script.
> >
> > ```bash theme={null}
> > #!/bin/bash
> > exec > /root/setup.log 2>&1
> > set -xe
> >
> > # Update system and install dependencies
> > sudo apt update -y
> > sudo apt install -y git nginx
> > git --version
> >
> > # Clone and setup project
> > git clone https://github.com/weam-ai/weam.git /root/project
> > cd /root/project
> > cp .env.example .env
> >
> > # Configure your domain (REPLACE WITH YOUR ACTUAL DOMAIN)
> > CUSTOM_DOMAIN="https://yourexampledomain.com"
> >
> > # Update environment variables with custom domain
> > sed -i.bak "s|http://localhost:4050|$CUSTOM_DOMAIN|g" .env
> > sed -i.bak "s|http://localhost:3000|$CUSTOM_DOMAIN|g" .env
> >
> > # Install SSL certificate tools
> > sudo apt install -y certbot python3-certbot-nginx
> >
> > # Extract domain name for nginx configuration
> > DOMAIN=$(echo "$CUSTOM_DOMAIN" | sed -E 's~^https?://~~')
> >
> > # Create Nginx configuration for your app
> > cat <<EOL | sudo tee /etc/nginx/sites-available/yourapp
> > server {
> >     listen 80;
> >     server_name $DOMAIN;
> >
> >     # Main application
> >     location / {
> >         proxy_pass http://localhost:3000;
> >         proxy_set_header Host \$host;
> >         proxy_set_header X-Real-IP \$remote_addr;
> >         proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
> >         proxy_set_header X-Forwarded-Proto \$scheme;
> >     }
> >
> >     # Node.js API endpoints
> >     location /napi/ {
> >         proxy_pass http://localhost:4050/napi/;
> >         proxy_http_version 1.1;
> >         proxy_set_header Host \$host;
> >         proxy_set_header X-Real-IP \$remote_addr;
> >         proxy_set_header Upgrade \$http_upgrade;
> >         proxy_set_header Connection 'upgrade';
> >     }
> >
> >     # MinIO Storage
> >     location /minio/ {
> >         proxy_pass http://localhost:9000/;
> >         proxy_set_header Host \$host;
> >         proxy_set_header X-Real-IP \$remote_addr;
> >     }
> > }
> > EOL
> >
> > # Enable the configuration
> > sudo ln -sf /etc/nginx/sites-available/yourapp /etc/nginx/sites-enabled/
> > sudo nginx -t && sudo systemctl reload nginx
> >
> > # Configure firewall
> > sudo ufw allow 80/tcp
> > sudo ufw allow 443/tcp
> >
> > echo "✅ Production setup completed successfully!"
> > ```
>
> **4. Create Droplet**
>
> Click **Create Droplet** and wait 2-3 minutes for initialization, then 5-10 minutes for the setup script to complete.
>
> **5. Connect and Deploy**
>
> Connect to your droplet via SSH:
>
> ```bash theme={null}
> ssh root@<DROPLET_IP>
> ```
>
> Navigate to the project directory and start the deployment:
>
> ```bash theme={null}
> # Check setup completion
> tail -f /root/setup.log
>
> # Navigate to project directory
> cd /root/project
>
> # Build the application (15-20 minutes)
> bash build.sh
>
> # Deploy with Docker Compose
> docker compose up --build
>
> # For background deployment
> docker compose up -d
> ```
>
> **6. Access Application**
>
> **Development Setup:**
>
> ```
> http://<DROPLET_IP>:3000/login
> ```
>
> **Production Setup:**
>
> ```
> https://yourexampledomain.com/login
> ```
>
> > [!NOTE]
> >
> > For production, ensure your domain's DNS A record points to your droplet's public IP address.

## SSL Certificate Setup (Production Only)

After your application is running and DNS is properly configured, enable free SSL certificates:

```bash theme={null}
# Replace with your actual domain
sudo certbot --nginx -d yourexampledomain.com

# Follow the interactive prompts to complete SSL setup
```

## Service Architecture

| Service | Port | Internal URL | Description |
| - | - | - | - |
| **Frontend (Next.js)** | 3000 | [http://localhost:3000](http://localhost:3000) | Main web interface |
| **Backend (Node.js)** | 4050 | [http://localhost:4050](http://localhost:4050) | API server |
| **MongoDB** | 27017 | Internal only | Database |
| **Redis** | 6379 | Internal only | Cache/sessions |

## Troubleshooting

> [tab] AWS EC2
>
> > [accordion] Instance Launch Issues
> >
> > **Common problems:**
> >
> > * Insufficient instance limits in your AWS account
> > * Security group not properly configured
> > * Key pair permissions too open
> >
> > **Solutions:**
> >
> > * Request limit increase in AWS Console
> > * Ensure security group allows SSH (22), HTTP (80), HTTPS (443)
> > * Set key pair permissions: `chmod 400 your-key.pem`
>
> > [accordion] SSH Connection Problems
> >
> > **Connection failures:**
> >
> > * Wrong key file or path
> > * Security group doesn't allow SSH
> > * Instance not fully initialized
> >
> > **Solutions:**
> >
> > ```bash theme={null}
> > # Correct SSH command format
> > ssh -i /path/to/your-key.pem ubuntu@<PUBLIC_IP>
> >
> > # Check security group allows port 22 from your IP
> > # Wait 5-10 minutes after launch for full initialization
> > ```
>
> > [accordion] Application Access Issues
> >
> > **Cannot reach application:**
> >
> > * Security group doesn't allow HTTP/HTTPS
> > * Application not started
> > * Wrong URL format
> >
> > **Solutions:**
> >
> > * Add inbound rules for ports 80, 443 (and 3000 for development)
> > * Check application status: `docker ps`
> > * Use correct URL format based on setup type
>
> > [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] DigitalOcean
>
> > [accordion] Droplet Creation Issues
> >
> > **Common problems:**
> >
> > * Account limits reached
> > * Payment method issues
> > * Region unavailability
> >
> > **Solutions:**
> >
> > * Check account limits in DigitalOcean console
> > * Verify billing information is current
> > * Try different region if current one is unavailable
>
> > [accordion] Docker Issues
> >
> > **If you selected plain Ubuntu instead of Docker image:**
> >
> > ```bash theme={null}
> > # Install Docker manually
> > curl -fsSL https://get.docker.com -o get-docker.sh
> > sh get-docker.sh
> > sudo usermod -aG docker $USER
> >
> > # Restart session or run:
> > newgrp docker
> > ```
>
> > [accordion] Firewall Problems
> >
> > **Port access issues:**
> >
> > ```bash theme={null}
> > # Check firewall status
> > sudo ufw status
> >
> > # Allow required ports
> > sudo ufw allow 22/tcp   # SSH
> > sudo ufw allow 80/tcp   # HTTP
> > sudo ufw allow 443/tcp  # HTTPS
> > sudo ufw allow 3000/tcp # Development (if needed)
> > ```
>
> > [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

> [!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]
>
> **Important Notes:**
>
> * The application requires HTTPS for production login
> * You must use a custom domain with SSL certificate for production
> * Development mode allows HTTP access via IP address
> * Build process takes 15-20 minutes on first deployment
> * Ensure adequate system resources to avoid build failures


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