Deploy on Cloud

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)

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

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)

   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:

   Development (No Domain)

   #!/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!"
   

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:

   ssh -i your-key.pem ubuntu@<EC2_PUBLIC_IP>
   

   Navigate to the project directory and start the build:

   # 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
   

   For production, ensure your domain’s DNS A record points to your EC2 instance’s public IP address.

SSL Certificate Setup (Production Only)

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

# 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	Main web interface
Backend (Node.js)	4050	http://localhost:4050	API server
MongoDB	27017	Internal only	Database
Redis	6379	Internal only	Cache/sessions

Troubleshooting

AWS EC2

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

SSH Connection Problems

Connection failures:

• Wrong key file or path
• Security group doesn’t allow SSH
• Instance not fully initialized

Solutions:

# 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

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

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

⚠️ 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.

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