realtimecursor/DEPLOYMENT.md

Real-time collaboration system with cursor tracking and approval workflow

# Deployment Guide

This guide explains how to deploy the RealtimeCursor API server and use the npm package.

## Option 1: Use the Hosted Service (Recommended)

The easiest way to use RealtimeCursor is to use our hosted service. The npm package is already configured to use this service by default.

```javascript
import { RealtimeCursor } from 'realtimecursor';

const cursor = new RealtimeCursor({
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe',
    color: '#3b82f6'
  }
  // No need to specify apiUrl, it defaults to the hosted service
});

cursor.connect();
```

## Option 2: Self-Host the API Server

If you prefer to host the API server yourself, follow these steps:

### Deploy to Render.com

1. Fork this repository
2. Sign up for a [Render](https://render.com) account
3. Create a new Web Service
4. Connect your GitHub repository
5. Configure the service:
   - Build Command: `cd api && npm install`
   - Start Command: `cd api && node server.js`
   - Environment Variables: `PORT=10000`

### Deploy to Heroku

1. Fork this repository
2. Sign up for a [Heroku](https://heroku.com) account
3. Create a new app
4. Connect your GitHub repository
5. Configure the app:
   - Buildpack: Node.js
   - Procfile: `web: cd api && node server.js`

### Deploy to AWS

1. Fork this repository
2. Sign up for an [AWS](https://aws.amazon.com) account
3. Create an EC2 instance
4. SSH into the instance
5. Clone your repository
6. Install Node.js
7. Run the server:
   ```bash
   cd api
   npm install
   node server.js
   ```

### Deploy with Docker

1. Build the Docker image:
   ```bash
   docker build -t realtimecursor-api -f Dockerfile.api .
   ```

2. Run the Docker container:
   ```bash
   docker run -p 3001:3001 realtimecursor-api
   ```

## Using a Custom API Server

If you're hosting the API server yourself, you need to specify the `apiUrl` when initializing the RealtimeCursor client:

```javascript
import { RealtimeCursor } from 'realtimecursor';

const cursor = new RealtimeCursor({
  apiUrl: 'https://your-api-server.com', // Your custom API server URL
  projectId: 'your-project-id',
  user: {
    id: 'user-123',
    name: 'John Doe',
    color: '#3b82f6'
  }
});

cursor.connect();
```

## Security Considerations

- The API server doesn't implement authentication by default. If you need authentication, you should add it to the server.
- Consider using HTTPS for your API server to encrypt the data in transit.
- Limit access to your API server using firewalls or other security measures.

## Scaling

If you need to scale the API server, consider:

- Using a load balancer to distribute traffic across multiple instances
- Using a database to store user data instead of in-memory storage
- Using Redis for pub/sub to handle real-time communication across multiple instances

## Troubleshooting

- If you're having connection issues, check that your API server is running and accessible
- If you're seeing CORS errors, make sure your API server is configured to allow requests from your client's domain
- If you're experiencing high latency, consider deploying your API server closer to your users