Skip to content

SETUP.md

Latest commit

 

History

History
253 lines (196 loc) · 5.62 KB

SETUP.md

File metadata and controls

253 lines (196 loc) · 5.62 KB

Setup Guide

This guide will help you set up the Real-Time Collaborative Document Editor on your local machine or server.

Quick Start

Option 1: Docker Compose (Recommended)

  1. Clone the repository

    git clone https://github.com/Anjan50/real-time-collaborative-editor.git
cd real-time-collaborative-editor

  2. Configure environment variables

    cp .env.example .env
# Edit .env with your AWS credentials

  3. Create DynamoDB table

    • Go to AWS Console → DynamoDB
    • Create table named SocketDocuments
    • Set partition key: id (String)
    • Leave other settings as default

  4. Start the application

    docker-compose up --build

  5. Access the application

    • Open browser: http://localhost
    • Create a new document or navigate to /editor/{document-id}

Option 2: Local Development

Backend Setup

  1. Navigate to backend directory

    cd backend

  2. Create virtual environment

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Set environment variables

    export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_DEFAULT_REGION=us-east-1

  5. Run the server

    uvicorn main:app --reload --port 8000

Frontend Setup

  1. Navigate to frontend directory

    cd frontend

  2. Install dependencies

    npm install

  3. Start development server

    npm start

  4. Access the application

AWS DynamoDB Setup

Creating the Table

  1. Log in to AWS Console
  2. Navigate to DynamoDB service
  3. Click "Create table"
  4. Configure:
    • Table name: SocketDocuments
    • Partition key: id (String)
    • Table settings: Use default settings
  5. Click "Create table"

Table Schema

{
  "TableName": "SocketDocuments",
  "KeySchema": [
    {
      "AttributeName": "id",
      "KeyType": "HASH"
    }
  ],
  "AttributeDefinitions": [
    {
      "AttributeName": "id",
      "AttributeType": "S"
    }
  ]
}

Environment Variables

Required Variables

Variable Description Example
AWS_ACCESS_KEY_ID AWS access key AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY AWS secret key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_DEFAULT_REGION AWS region us-east-1

Optional Variables (for Docker deployment)

Variable Description Example
ECR_REGISTRY AWS ECR registry URL 123456789.dkr.ecr.us-east-1.amazonaws.com
GIT_BRANCH Git branch name main

Troubleshooting

Common Issues

1. DynamoDB Connection Error

Problem: Unable to locate credentials Solution:

  • Verify AWS credentials in .env file
  • Check AWS credentials have DynamoDB permissions
  • Ensure AWS_DEFAULT_REGION is set correctly

2. WebSocket Connection Failed

Problem: WebSocket connection not establishing Solution:

  • Check backend is running on port 8000
  • Verify Nginx configuration if using Docker
  • Check firewall settings

3. Port Already in Use

Problem: Address already in use Solution:

  • Change port in docker-compose.yml
  • Or stop the process using the port: 
    # Find process
lsof -i :8000  # Linux/Mac
netstat -ano | findstr :8000  # Windows

# Kill process
kill -9 <PID>  # Linux/Mac
taskkill /PID <PID> /F  # Windows

4. Docker Build Fails

Problem: Build errors during docker-compose up --build Solution:

  • Check Docker is running
  • Verify Docker has enough resources allocated
  • Try rebuilding without cache: docker-compose build --no-cache

Production Deployment

AWS EC2 Deployment

  1. Launch EC2 instance

    • Choose Ubuntu 20.04 or later
    • Configure security group to allow ports 80, 443, 22

  2. Install Docker and Docker Compose

    sudo apt update
sudo apt install docker.io docker-compose -y
sudo usermod -aG docker $USER

  3. Clone and configure

    git clone https://github.com/Anjan50/real-time-collaborative-editor.git
cd real-time-collaborative-editor
cp .env.example .env
# Edit .env with production credentials

  4. Start services

    sudo docker-compose up -d

  5. Set up domain (optional)

    • Point domain to EC2 public IP
    • Configure SSL certificate (Let's Encrypt recommended)

Testing

Manual Testing

  1. Test document creation

    • Navigate to http://localhost
    • Click "New Document" or go to /editor/{new-id}
    • Verify document loads

  2. Test real-time collaboration

    • Open document in two browser windows
    • Type in one window
    • Verify changes appear in other window

  3. Test persistence

    • Create/edit document
    • Close browser
    • Reopen document
    • Verify content is saved

API Testing

Use curl or Postman to test endpoints:

# Health check
curl http://localhost/api/hello

# Get document
curl http://localhost/api/database/documents/get/{document-id}

# Create document
curl -X POST http://localhost/api/database/documents \
  -H "Content-Type: application/json" \
  -d '{"id": "test-id", "Data": "Hello World"}'

Next Steps