Skip to content

README.md

Latest commit

 

History

History
116 lines (84 loc) · 4.45 KB

README.md

File metadata and controls

116 lines (84 loc) · 4.45 KB
Raw

SyncCode

SyncCode is a production-ready, real-time collaborative coding workspace designed to enable developers to code together seamlessly with shared editor states, live cursor tracking, and secure, isolated execution of code in multiple programming languages.

🚀 Key Features

  • Real-time Collaborative Editing: Seamless code collaboration powered by Yjs CRDTs over WebSockets.
  • Live User Presence: Track remote cursor positions, selection ranges, active typing states, and online users in real-time.
  • Multi-language Sandbox Execution: Safely run Python, JavaScript, and C++ code. Executions are strictly isolated inside Docker containers with custom CPU/memory caps, disabled networking, and read-only filesystems.
  • Production Security: Secured with JSON Web Tokens (JWT) for authentication, custom input sanitization, rate-limiting on endpoints, and Docker security isolation.
  • Scalable Core Architecture: Utilizes Redis for horizontal scaling and adapter syncing across multiple WebSocket server instances.
  • Full Observability: Integrated Prometheus metrics endpoints and Grafana dashboards for monitoring system status and container metrics.

📁 Repository Structure

├── synccode_frontend/     # React + Vite frontend client
├── synccode_backend/      # Express + Socket.io collaboration server
├── synccode-executor/     # Sandboxed code execution service (Docker based)
├── monitoring/            # Prometheus config and Grafana provision files
├── nginx/                 # Nginx configurations for reverse-proxy routing
├── Docker-compose.yml     # Local orchestration stack
├── SyncCode-local.sh      # All-in-one setup bash script
└── architecture.md        # Technical architectural design document

For a detailed walkthrough of the system flow, database syncs, and sandbox architecture, read architecture.md.

⚙️ Configuration & Environment Variables

All main services use environment variables. A template is provided in env.example.

Setup Environment

Create a .env file at the project root by copying the template:

cp env.example .env

The setup script SyncCode-local.sh automatically creates and populates the .env file with a cryptographically secure JWT_SECRET key if one doesn't exist.

🛠️ Getting Started

📋 Prerequisites

Make sure you have the following installed on your machine:

Method A: Docker Compose Deployment (Recommended)

To run the complete production-grade stack (Frontend, Backend, Executor, Redis, Nginx, Prometheus, Grafana) automatically:

  1. Run the local setup script:

    ./SyncCode-local.sh

    This pulls the required sandbox Docker images (node:24-alpine, python:3.11-alpine, gcc:13-alpine), installs Node dependencies, and creates runtime configs.

  2. Start the services:

    ./start.sh

  3. Access the applications:

  4. Stop the services:

    ./stop.sh

Method B: Native Setup (No Containers)

If you prefer to run services natively on your local environment:

  1. Start Redis Server on your default port (6379).
  2. Run the native start script: 
    ./start-native.sh
    This launches the backend server and code executor as background processes and logs stdout to ./logs/.
  3. Stop native processes: 
    ./stop-native.sh

🧪 Testing and Verification

To verify that the backend and executor services are operational:

# Check Backend Health Status
curl http://localhost:3001/health

# Check Code Executor Health Status
curl http://localhost:3002/health

Both endpoints should return status "healthy" along with runtime statistics.